Umfangreiche Vorlage für die Projektdokumentation inkl. Beispielen zum Download

[stefan.macke]

Guten Abend zusammen.

Ich habe in mühevoller Kleinarbeit eine LaTeX-Vorlage für die Projektdokumentation zusammengestellt: LaTeX-Vorlage für IHK-Projektdokumentationen zum Fachinformatiker Anwendungsentwicklung.

Die Vorlage dürfte nicht nur für LaTeX-Nutzer oder Anwendungsentwickler interessant sein, sondern auch für Azubis in anderen IT-Berufen, da sie neben dem Layout auch eine Vorstrukturierung möglicher Inhalte und viele praktische Beispiele umfasst. Konkret werden die folgenden Punkte abgedeckt:

• Hinweise zu den geforderten Inhalten mit Quellenangaben
  
• Deckblatt
  
• Inhaltsverzeichnis
  
• Abbildungs- und Tabellenverzeichnis
  
• Abkürzungsverzeichnis/Glossar
  
• vorstrukturierte Kapitel für den eigentlichen Inhalt mit Stichpunkten und Beispielen (Zeitplanung, Stundensatzrechnung, Use Case-/Klassendiagramm, ERM, Mockups u.a.)
  
• Literaturverzeichnis
  
• Eidesstattliche Erklärung
  
• Anhang
  

Ich würde mich über Feedback - gerne auch ein kritisches - zur Vorlage freuen.

Viele Grüße!

Stefan

[flashpixx]

Zur Info:

Du baust keinen Glossar, sondern ein Acronym Verzeichnis. Für Glossare gibt es CTAN web interface: package glossaries

Ich würde von natbib bezügl. der Flexibilität abraten und statt dessen CTAN web interface: package biblatex verwenden

\clearpages sollte man mit Bedacht verwenden, im Normalfall macht LaTeX das viel besser. Anführungszeichen werden mit \glqq bzw \grqq (für die deutschen) codiert. Ansonsten finde ich diese Struktur extrem unübersichtlich, gerade die Präambel sollte man zusammenhalten und nicht so auseinander reißen, falls man ggf Paketoptionen anpassen muss. Diese ganze eigenen Definitionen sind im Grunde zu viel, weil man direkt die Befehle eingeben kann. Bei Graphiken sollte man eine figure-Umgebung (ggf floatfig) verwenden und nicht fbox. Im PDF ist das Inhaltsverzeichnis nicht klickbar, d.h. man kann nicht direkt die Kapitel anspringen.

Für Use-Case & Klassendiagramme gibt es Welcome to MetaUML, UML for LaTeX/MetaPost und für Diagramme aller Art TikZ and PGF | TeXample.net

[stefan.macke]

Hallo flashpixx.

Erstmal danke für das Feedback.

Du baust keinen Glossar, sondern ein Acronym Verzeichnis.

Korrekt, aber das war auch so gewollt. Da habe ich mich bei der Benennung etwas vertan. Dein Glossar schaue ich mir mal an und baue es ggfs. ein.

Ich würde von natbib bezügl. der Flexibilität abraten und statt dessen CTAN web interface: package biblatex verwenden.

Ok, das werde ich mir mal anschauen und ggfs. einbauen.

\clearpages sollte man mit Bedacht verwenden, im Normalfall macht LaTeX das viel besser.

Richtig. Aber die von mir gesetzten \clearpages sind durchaus mit Bedacht gesetzt :-) Ich habe sie erst eingefügt, nachdem mir im fertigen Dokument nicht gefallen hat, wie LaTeX einige Seiten umgebrochen hat.

Anführungszeichen werden mit \glqq bzw \grqq (für die deutschen) codiert.

Bei Verwendung des Pakets german kann man durchaus auch die von mir verwendete Schreibweise nutzen: siehe Wikibooks.

Ansonsten finde ich diese Struktur extrem unübersichtlich, gerade die Präambel sollte man zusammenhalten und nicht so auseinander reißen, falls man ggf Paketoptionen anpassen muss.

Ok, das mag für dich gelten. Ich persönlich finde die Struktur so sehr viel übersichtlicher, da Einsteiger z.B. nur die Seitenstil.tex editieren müssen und nicht von hunderten Packagedefinitionen erschlagen werden.

Diese ganze eigenen Definitionen sind im Grunde zu viel, weil man direkt die Befehle eingeben kann.

Das sehe ich nicht so. Die von mir definierten Befehle sorgen zum einen dafür, dass man bestimmte häufige LaTeX-Befehle nicht mehrfach verwenden und damit auch mehrfach anpassen muss, wenn man die Darstellung ändern möchte (z.B. \itemd). Zum anderen dienen sie der semantischen Textauszeichnung, wodurch eine Entkopplung von Bedeutung und Darstellung des Textes erreicht wird, was wiederum zu einer einfacheren Änderung der Darstellung führt (z.B. alle \Eingaben kursiv anstatt fett). Ganz zu schweigen von typographischen Ungeheuern wie "z.\,B.", dem ich \zB durchaus vorziehe ;-)

Bei Graphiken sollte man eine figure-Umgebung (ggf floatfig) verwenden und nicht fbox.

Das mache ich ja auch. fbox wird lediglich für eine einzige Ausnahme verwendet (zweiseitiges PDF im Anhang).

Im PDF ist das Inhaltsverzeichnis nicht klickbar, d.h. man kann nicht direkt die Kapitel anspringen.

Das ist falsch. Es ist allerdings nur die Seitenzahl verlinkt und nicht der Kapiteltext, da ich das optisch nicht so ansprechend finde. Siehe linktocpage in Packages.tex.

Für Use-Case & Klassendiagramme gibt es Welcome to MetaUML, UML for LaTeX/MetaPost und für Diagramme aller Art TikZ and PGF | TeXample.net

Danke, das kannte ich noch nicht. Werde mir das mal anschauen.

Viele Grüße!

Stefan

[flashpixx]

Richtig. Aber die von mir gesetzten \clearpages sind durchaus mit Bedacht gesetzt :-) Ich habe sie erst eingefügt, nachdem mir im fertigen Dokument nicht gefallen hat, wie LaTeX einige Seiten umgebrochen hat.

Meines Wissens wird ja z.B. bei einem \section automatisch ein Seitenumbruch erzeugt

Bei Verwendung des Pakets german kann man durchaus auch die von mir verwendete Schreibweise nutzen: siehe Wikibooks.

Das stimmt schon, nur sollte man z.B. bei

"a

aufpassen, weil dabei wird dann schnell ein ä draus. Deshalb würde ich entweder csquote oder eben die entsprechende \glqq Variante nehmen. Gerade bei Verbatim Umgebungen passiert das schnell

Ok, das mag für dich gelten. Ich persönlich finde die Struktur so sehr viel übersichtlicher, da Einsteiger z.B. nur die Seitenstil.tex editieren müssen und nicht von hunderten Packagedefinitionen erschlagen werden.

Bei komplexeren Arbeiten (> 50 Seiten) empfehle ich letztendlich immer, dass man kapitelweise die Daten organisiert, so dass man im Hauptdokument dann schnell die Kapitel vertauschen kann. Jedes Kapitel wird dann analog strukturiert, so dass man im besten Fall pro Subkapitel eine Datei hat mit den entsprechenden Kapiteldaten (Bilder, etc). Zusätzlich würde ich zu Git oder SVN raten

Ganz zu schweigen von typographischen Ungeheuern wie "z.\,B.", dem ich \zB durchaus vorziehe ;-)

Bei diesem Fall kannst Du aber nicht darauf eingehen, wenn das z.B. an einem Satzanfang steht, Du müsstest somit für jeden Fall ein entsprechendes Kommando definieren bzw. das Kommando mit Parametern auszeichnen. Du definierst z.B.

\newcommand{\datum}{\today}

das letztendlich unnötig ist, denn Du kannst direkt \today nehmen. Ich würde letztendlich immer zu Orthogonaler Befehlssatz raten, um die Übersicht zu behalten. Ich verweise auch auf Deine doppelte Nutzung des Befehls \title, siehe http://www.weinelt.de/latex/title.html

Das mache ich ja auch. fbox wird lediglich für eine einzige Ausnahme verwendet (zweiseitiges PDF im Anhang).

Wofür dann eine fbox? Subfig sollte dies innerhalb der figure-Umgebung auch bieten

Das ist falsch. Es ist allerdings nur die Seitenzahl verlinkt und nicht der Kapiteltext, da ich das optisch nicht so ansprechend finde. Siehe linktocpage in Packages.tex.

Das stimmt, aber in einem Dokument, was am Monitor betrachtet wird, sollte man die Links so auszeichnen, dass sie auch als solche erkannt werden. Ich bin davon ausgegangen, dass die Zahlen nur in einer anderen Farbe angegeben wurden.

Ebenso würde ich dazu raten, dass man Ordner- und Dateinamen klein schreibt, damit ggf keine Probleme entstehen, wenn die Daten mal auf ein unixoxides System portiert werden sollten.

Bearbeitet 15. Februar 2012 von flashpixx

[stefan.macke]

Hallo flashpixx.

Meines Wissens wird ja z.B. bei einem \section automatisch ein Seitenumbruch erzeugt

Bei der von mir verwendeten Dokumentenklasse wird kein Seitenumbruch bei einer Section erzeugt. Die manuellen Umbrüche habe ich hauptsächlich deswegen gesetzt, weil einige Grafiken sonst ungünstig platziert worden wären.

Bei komplexeren Arbeiten (> 50 Seiten) empfehle ich letztendlich immer, dass man kapitelweise die Daten organisiert, so dass man im Hauptdokument dann schnell die Kapitel vertauschen kann. Jedes Kapitel wird dann analog strukturiert, so dass man im besten Fall pro Subkapitel eine Datei hat mit den entsprechenden Kapiteldaten (Bilder, etc).

Deine vorgeschlagene Inhaltsstruktur habe ich ja genauso umgesetzt: In der Inhalt.tex kann man die einzelnen Kapitel beliebig hin- und herschieben. Und jedes Kapitel hat eine eigene Datei unter \Inhalt.

Bei diesem Fall kannst Du aber nicht darauf eingehen, wenn das z.B. an einem Satzanfang steht

Das Problem mit dem "z.B." am Satzanfang stimmt natürlich, wobei ich persönlich keinen neuen Satz damit beginnen würde ;-)

Du kannst direkt \today nehmen

Das \today ist lediglich ein Platzhalter. Das konkrete Datum dürfte bei einer echten Arbeit ja eh fix sein (also z.B. das Abgabedatum) und gar nicht dynamisch erzeugt werden. Ich ändere das mal in der nächsten Version auf ein fixes Datum ab, dann wird deutlicher, dass man es ändern muss.

Wofür dann eine fbox? Subfig sollte dies innerhalb der figure-Umgebung auch bieten

Das Beispiel mit der fbox stammt nicht von mir. Ich werde mir deinen Vorschlag mal anschauen.

Ebenso würde ich dazu raten, dass man Ordner- und Dateinamen klein schreibt, damit ggf keine Probleme entstehen, wenn die Daten mal auf ein unixoxides System portiert werden sollten.

Das verstehe ich nicht ganz: Ich verwende in den Dokumenten doch die korrekte (Groß-)Schreibweise der inkludierten Dateinamen. Warum sollte das unter Linux nicht funktionieren?

Viele Grüße!

Stefan

[flashpixx]

Bei der von mir verwendeten Dokumentenklasse wird kein Seitenumbruch bei einer Section erzeugt. Die manuellen Umbrüche habe ich hauptsächlich deswegen gesetzt, weil einige Grafiken sonst ungünstig platziert worden wären.

Ich nutze für meine Dokumente KOMA-Script Documentation Project | Aktive Anwender verbessern KOMA-Script. bzw LaTeX-Wörterbuch: fancyhdr

Deine vorgeschlagene Inhaltsstruktur habe ich ja genauso umgesetzt: In der Inhalt.tex kann man die einzelnen Kapitel beliebig hin- und herschieben. Und jedes Kapitel hat eine eigene Datei unter \Inhalt.

Nein, z.B. liegen die ERDs und Klassendiagramme unter Bilder. Deshalb war ja mein Hinweis, pro Kapitel einen Ordner inkl aller zum Kapitel zugehörigen Dokumenten

Das Problem mit dem "z.B." am Satzanfang stimmt natürlich, wobei ich persönlich keinen neuen Satz damit beginnen würde ;-)

Das war ja nur der Hinweis bezüglich der Vollständigkeit :-P

Das \today ist lediglich ein Platzhalter. Das konkrete Datum dürfte bei einer echten Arbeit ja eh fix sein (also z.B. das Abgabedatum) und gar nicht dynamisch erzeugt werden. Ich ändere das mal in der nächsten Version auf ein fixes Datum ab, dann wird deutlicher, dass man es ändern muss.

Das denke ich wäre sinnvoller

Das verstehe ich nicht ganz: Ich verwende in den Dokumenten doch die korrekte (Groß-)Schreibweise der inkludierten Dateinamen. Warum sollte das unter Linux nicht funktionieren?

Natürlich so lange man es konsistent macht. Ich habe schon mehrfach den Fall gehabt, dass jemand der TeX unter Windows benutzt eben nicht auf korrekte Groß-Klein-Schreibung achtet (manche TeX Interpreter lassen das durchgehen bzw. akzeptieren auch Backslash anstatt Slash als Pfadtrenner). Wenn dann die TeX Daten nun auf unixoxides System kopiert werden, weil z.B. der Laptop kaputt ist, dann hat man sehr viel Arbeit das zu korrigieren. Deswegen wäre da eben mein Vorschlag generell alles mit Kleinbuchstaben zu notieren.

[blubbla]

Kleine Zwischenfrage (auch wenns praktisch Offtopic ist):

Welchen Editor verwendet ihr denn zum erstellen eurer Dokumente?

Ich hab früher das TeXnicCenter für Berichte und Abschlussarbeit verwendet. Besonders die Literaturverwaltung hat mir ganz gut gefallen (also die Anzeige der mit Bibtex verwalteten Quellen) - und auch die Darstellung der Struktur etc.

Nun hab ich mir mal TexWorks installiert - immerhin der Standard-Editor von TexLive. Und dort gibt es ja wirklich garnichts. Er ist schnell, stabil und auch sehr elegant mit der PDF-Erzeugung - aber sonst doch relativ "nackt". Oder gewöhnt man sich irgendwann daran?

[stefan.macke]

Ich nutze für meine Dokumente KOMA-Script Documentation Project | Aktive Anwender verbessern KOMA-Script. bzw LaTeX-Wörterbuch: fancyhdr

Das schaue ich mir mal an!

Nein, z.B. liegen die ERDs und Klassendiagramme unter Bilder

Das stimmt, aber mir gefällt es besser, wenn alle Bilder in einem Ordner liegen. Ist wohl Geschmackssache und kann man ja anpassen, wenn man mag.

Groß-Klein-Schreibung

Ok, das baue ich dann mal ein.

Welchen Editor verwendet ihr denn zum erstellen eurer Dokumente?

Ich benutze TeXlipse in Zusammenarbeit mit SumatraPDF. Habe vorher viel mit LaTeX Editor gearbeitet, aber TeXlipse ist schon sehr cool. Du kannst auch BibTeX etc. damit bearbeiten und es hat halt die bekannten Funktionen und Shortcuts von Eclipse.

Viele Grüße!

Stefan

[flashpixx]

Ich geb mal meine Config an, ich arbeite unter OSX 10.6 mit

TeX Live (2011)

BibDesk (für Bibliographie), das direkt auf CiteULike: Everyone's library zugreift

Delicious Library für die Verwaltung meiner Bücher

Texmaker bzw. TextMate zum Schreiben

Als Alternative für die Bibliographie gibt es noch JabRef

Das TexnicCenter kann meines Wissens kein UTF-8, so dass das schon mal direkt rausfällt. MikTex nehme ich nicht, weil das wieder nur windows-only ist. TexLive gibt es für alle OS, somit wieder konsistent.

[stefan.macke]

Für alle, die zwar gerne die Vorlage nutzen würden, aber von LaTeX abgeschreckt werden, habe ich nun eine mehrteilige Einführung in LaTeX in Form von kurzen Screencasts erstellt, die man sich hier kostenlos anschauen kann: LaTeX-Einführung | Fachinformatiker Anwendungsentwicklung. Die Quelltexte und Beispiel-PDFs sind bei Github verfügbar: StefanMacke/latex-einfuehrung

Weiterhin bin ich für jegliches Feedback zur Vorlage dankbar. Die neue Adresse zum Download ist: Vorlage für die Projektdokumentation | Fachinformatiker Anwendungsentwicklung.

[Akku]

Ich könnte mir vorstellen, dass so mancher jetzt, ob der Diskussion um die korrekte Benutzung von Latex, eher abgeschreckt wird. Da wird einem ja schwindelig. Daher bitte solche Diskussionen im entsprechenden Fachbereich führen. Danke.

[stefan.macke]

Hallo Akku,

da wir uns in einem Forum für Fachinformatiker bewegen, sollte doch wohl niemand von einer kleinen Markupsprache abgeschreckt werden, oder? Die meisten Leser hier kennen wohl auch HTML. Das ist letztlich auch nichts anderes.

Insbesondere wenn es um die Erstellung des Abschlussprojekts geht, das ein zentraler Teil der Abschlussnote ist. Ich denke, dafür kann man ruhig mal ein vernünftiges Textsatzsystem nutzen. Ein ehemaliger Kollege von mir hat seine Abschlussdokumentation z.B. komplett mit InDesign gesetzt. Das sieht alles deutlich ansprechender aus als die "klassische" Word-Datei.

Natürlich will ich niemandem vorschreiben, wie er seine Dokumentation zu schreiben hat. Meine Auszubildenden schreiben jetzt seit mehreren Jahren ihre Ausarbeitungen mit LaTeX und bislang hat das immer sehr gut geklappt. Gerade als Anwendungsentwickler sollte einem das "Programmieren" von Dokumenten doch liegen. Außerdem kann man den Text versionieren, die Dateigrößen sind gering usw.

Also kurz gesagt: Probieren geht über diskutieren. Für alle, die LaTeX ausprobieren wollen, gibt es jedenfalls die oben verlinkte Vorlage. Bei Fragen und Anregungen meldet euch gerne!

Viele Grüße!

Stefan

[Akku]

Es ging mir bei meinem Kommentar lediglich darum, die Diskussion um die "richtige" Benutzung von Latex aus eurer Sichtweise ein zu dämmen. Ob jemand Latex nutzen will ist mir Schnurz piep egal und ob sich jemand mit der "richtigen" Aufbereitung der Dokumentation mit und durch Latex auseinander setzen will ebenfalls.

Ich rate jedoch dringend davor ab, kurz vor der Prüfung eine Auseinandersetzung mit Latex zu wagen. Dieser Schuss kann sehr schnell nach hinten los gehen wenn man feststellt, dass die Doku nicht rechtzeitig fertig gestellt werden kann, weil man das System Latex vielleicht doch nicht versteht (aus welchen Gründen auch immer).

Mal davon abgesehen: ist es nicht möglich eine andere Form des Downloads anzubieten. Der Link auf deine Seite ist schließlich mit Werbung versehen, die bei mir ein leichtes unbehagen auslöst. Wir haben hie im Forum einen Downloadbereich also nutze diesen bitte.

Bearbeitet 4. März 2015 von Akku

[mfk'); DROP TABLE Users;--]

Insbesondere wenn es um die Erstellung des Abschlussprojekts geht, das ein zentraler Teil der Abschlussnote ist. Ich denke, dafür kann man ruhig mal ein vernünftiges Textsatzsystem nutzen. Ein ehemaliger Kollege von mir hat seine Abschlussdokumentation z.B. komplett mit InDesign gesetzt. Das sieht alles deutlich ansprechender aus als die "klassische" Word-Datei.

Wie schätzt du die Gefahr ein, dass du eine Dokumentation schlechter bewertest, nur weil du erkennst, dass sie nicht mit dem Textsystem deiner Wahl verfasst wurde, sondern eben mit Word? Kannst du ausschließen, dass für dich eine Dokumentation schon allein deshalb weniger "ansprechend" wirkt, weil du erkennen kannst, dass Word zum Einsatz kam?

[stefan.macke]

Ich rate jedoch dringend davor ab, kurz vor der Prüfung eine Auseinandersetzung mit Latex zu wagen.

Da stimme ich dir völlig zu. Daher schreiben meine Auszubildenden auch schon im ersten Ausbildungsjahr ihre Ausarbeitungen mit LaTeX.

Der Link auf deine Seite ist schließlich mit Werbung versehen.

Alle angebotenen Inhalte sind kostenlos und enthalten keine Werbung. Die Videos liegen bei YouTube und der Code bei Github. Die Vorlage steht sogar unter Creative Commons-Lizenz und darf nach Belieben genutzt und angepasst werden.

Wie schätzt du die Gefahr ein, dass du eine Dokumentation schlechter bewertest, nur weil du erkennst, dass sie nicht mit dem Textsystem deiner Wahl verfasst wurde, sondern eben mit Word?

Die Gefahr besteht nicht. Ich bewerte Dokumentationen ausschließlich nach ihrem Inhalt. Es gibt aber ja auch einen von der IHK vorgegebenen Bewertungspunkt "Formelle Gestaltung", der Dinge wie Inhaltsverzeichnis, Kopfzeile, Verweise, Anhang usw. beinhaltet. Und diesbzgl. habe ich die Erfahrung gemacht, dass viele Prüflinge diese Inhalte mit Word nicht korrekt umsetzen können. Das ist aber kein Problem von Word, sondern ein Problem des Prüflings. LaTeX macht einem die korrekte formelle Gestaltung des Dokuments aus meiner Sicht einfacher. Daher empfehle ich es. Man kann selbstverständlich auch mit Word eine perfekte Dokumentation schreiben (und ich gebe zu, die meisten "sehr guten" Dokumentationen, die ich gelesen habe, wurden mit Word geschrieben).