[0:00] Hi, hier ist Stefan. In dieser Podcast-Episode geht es um die Projektdokumentation. Wenn du dazu noch mehr Informationen von mir haben willst, dann schau doch mal auf meiner Website vorbei unter dieperfekteprojektdokumentation.de. Und jetzt viel Spaß mit der Podcast-Episode.

[0:15] Herzlich willkommen zum Anwendungsentwickler-Podcast, dem Podcast rund um die Ausbildung zum Fachinformatiker für Anwendungsentwicklung. In dieser Episode geht es um das Layout der Projektdokumentation. Viel Spaß!

[0:31] Hallo und herzlich willkommen zur 31. Episode des Anwendungsentwickler-Podcasts. Mein Name ist Stefan Macke und heute möchte ich mal ein bisschen was über das Layout der Projektdokumentation erzählen.

[0:50] In den letzten vier Episoden habe ich mich ja intensiv über die Inhalte und die Gliederung der Projektdokumentation ausgelassen und heute erzähle ich ein bisschen was zum Layout. Das heißt, wie die Projektdokumentation optisch ansprechend gestaltet werden kann bzw. was ihr vielleicht berücksichtigen solltet. Was optisch ansprechend ist, ist ja vielleicht ein bisschen Geschmackssache. Aber so ein paar allgemeine Grundsätze solltet ihr schon berücksichtigen und ein paar davon habe ich zusammengestellt.

[1:18] Ich habe das Ganze mal gegliedert heute in drei Oberpunkte. In den Seitenstil, den Text und die Artefakte, die ihr in eurer Dokumentation platziert. Fangen wir doch einfach mal direkt an mit dem Seitenstil. Und da fange ich als allererstes mal mit einem ganz wichtigen Thema, zumindest für mich als Prüfer an, nämlich der Seitennummerierung.

[1:37] Ihr habt üblicherweise von eurer IHK eine Vorgabe bezüglich des Umfangs der Projektdokumentation bekommen. In meinem Fall ist es immer so, dass die Projektdokumentation 15 Seiten Fließtext und maximal 25 Seiten Anhang umfassen darf. Nicht eingerechnet werden dabei irgendwelche Verzeichnisse, das Deckblatt und die Eiseschattelerklärung usw.

[1:58] Also insgesamt habt ihr eigentlich 40 Seiten Platz für eure Inhalte, zumindest bei meiner IHK. Und dann finde ich es immer ganz wichtig, wenn ich als Prüfer direkt sehen kann, ob ihr diese Vorgaben auch eingehalten habt. Und das kann ich ganz oft nicht, denn leider wird in vielen Dokumentationen von der ersten Seite an, manchmal sogar mit dem Deckblatt beginnend, die Projektdokumentation durchnummeriert, sodass ich dann nach den ganzen Verzeichnissen irgendwo auf Seite 7 mit der Einleitung beginne.

[2:22] Und dann darf ich mir selber ausrechnen, wie viele Seiten ihr dann tatsächlich für den Fließtext benutzt habt. Ich finde es immer schöner, wenn man das direkt sehen kann. Und es ist eigentlich auch guter Stil, wenn ihr euch mal andere Arbeiten anschaut, wird es auch so sein, dass der Fließtext normalerweise einheitlich durchnummeriert wird und alles vor dem Text wird anders nummeriert und alles nach dem Text nochmal anders.

[2:41] Ich persönlich würde zum Beispiel anfangen mit großen römischen Buchstaben. Das würde ich benutzen, um alles vor dem Text durchzunummerieren und den Fließtext selber dann wie gewohnt in arabischen Ziffern und nach dem Text mache ich dann mit kleinen römischen Buchstaben weiter. Aber das muss jeder selber wissen.

[2:59] Aber den Fließtext würde ich erwarten, dass der arabisch durchnummeriert wird und zwar beginnend bei 1. Das heißt, die erste Seite der Einleitung sollte die Seitenzahl 1 haben und dann sollte, zumindest in meinem Fall, die letzte Seite des Fließtextes die Seitenzahl 15 haben. Und wenn sie dann die Seitenzahl 13 oder 17 hat, dann weiß ich wenigstens sofort, aha, überzogen bzw. zu wenig Inhalt.

[3:21] Ich meine, sind wir ganz ehrlich, ich bin alt genug, ich kann die Seiten selber zählen. Das mache ich auch, wenn ich irgendwo keine vernünftigen Seitenzahlen habe, fange ich bei der Einleitung an und zähle die Seiten durch. Das mache ich sowieso bei jeder Dokumentation, habe ich ja beim letzten Mal schon erwähnt. Ich ziehe nämlich alles, was an großen Artefakten im Inhalt platziert wurde oder leere halbe Seiten oder sowas einfach ab, sodass ich also wirklich auch auf eine Netto-Seitenzahl komme. Das muss ich sowieso bei jeder Dokumentation machen. Aber ihr könnt mir durchaus die Arbeit etwas leichter machen, wenn ihr das wenigstens vernünftig arabisch durchnummeriert.

[3:51] Also, das ist das Erste. Achtet darauf, dass die Seitenzahlen vernünftig sind und dass sie auch zum Beispiel unten rechts auf der Seite platziert sind oder unten in der Mitte, das will ich noch nicht mal vorgeben. Aber auf jeden Fall so, dass ich beim Durchblättern schnell die Seite finde. Wenn ihr zum Beispiel irgendwelche Verweise gesetzt habt, dass ich sofort die Seite finden kann und nicht wirklich ewig durchblättern muss und suchen muss.

[4:10] Nächster Tipp. Genau das, was ich eigentlich gerade schon erwähnt habe, nämlich keinen unnötigen Leerraum lassen. Es ist unnötig, bei einer 15-seitigen Arbeit zum Beispiel vor Kapitelüberschriften Seitenumbrüche zu erzeugen. Dazu ist die Arbeit zu kurz. Ich muss dort also nicht komplette Teile oder Kapitel voneinander so abgrenzen, dass ich da also eine halbe Seite Leerraum dazwischen brauche. Das ist nicht nötig.

[4:33] Im Gegenteil, hier ist es sogar kontraproduktiv. Ich habe es gerade gesagt, wenn ihr das vor jedem Kapitel macht und ihr habt drei, vier Kapitel oder sagen wir mal eher sieben, acht Kapitel, dann kommt ihr netto schon auf vier, fünf Seiten, die da fehlen, wenn da immer eine halbe Seite Platz dazwischen ist. Also lasst das sein, macht keine Seitenumbrüche vor, Überschriften, lasst vielleicht ein bisschen Abstand, das ist völlig in Ordnung, aber nicht eine halbe Seite oder teilweise habe ich sogar Dokumentationen gesehen, wo eine Viertelseite geschrieben ist und dann kommt der Rest der Seite, der Leerraum ist.

[5:01] Und das geht gar nicht. Das ist verschenkter Platz und das muss ich einfach auch dann bei der Benotung berücksichtigen, wenn ihr dort also teilweise mehrere Seiten Fließtext, die ihr hättet schreiben können, einfach nicht nutzt, weil eben unnötiger Leerraum da produziert wurde.

[5:15] Gut, wenn wir schon bei dem Inhalt der Projektdokumentation so ein bisschen sind, achtet darauf, dass ihr maximal drei Gliederungsebenen verwendet. Ich würde sogar in der Projektdokumentation dazu raten, maximal zwei Gliederungsebenen zu benutzen.

[5:28] Bei 15 Seiten müsst ihr also nicht Kapitel 1.3.4.7, 1.3.4.8 und so weiter erzeugen. Das ist total unnötig. Das zeugt eher daher, dass ihr eure Gedanken nicht vernünftig ordnen könnt und die nicht in eine vernünftige, flache Struktur einfassen könnt.

[5:46] Bei 15 Seiten ist also meiner Meinung nach maximal die dritte Überschriftenebene noch sinnvoll. Alles darunter ist viel zu detailliert. Wie lange sollen dann diese Unterkapitel werden? Zwei, drei Sätze, das ist einfach nicht sinnvoll.

[6:00] Versucht eure Projektphasen so zu strukturieren, wie ihr das Projekt durchgeführt habt. Das hatte ich in den letzten Episoden ja schon erwähnt, wie ihr das aufbauen könnt. Und dann kommt ihr locker auf 7, 8, 9 Oberkapitel eurer Dokumentation.

[6:14] Und wenn ihr mal durchrechnet, 15 geteilt durch 8, dann sind wir schon bei unter einer halben Seite pro Kapitel. Und wenn ihr dann noch drei Unterüberschriften dort anlegt, das ist völlig überdimensioniert. Also maximal Ebene 2 wäre meine Empfehlung. Alles darunter ist viel zu detailliert.

[6:32] Das nächste, was man vermeiden sollte, wenn man auf den Seitenstil schaut, sind die sogenannten Hurenkinder bzw. Schusterjungen. Hurenkinder, das sind Zeilen von Absätzen, die alleine auf der Folgeseite stehen.

[6:48] Das heißt, angenommen, ich habe auf einer Seite einen Absatz am Ende der Seite, aber die letzte Zeile dieses Absatzes passt nicht mehr auf die Seite, dann rutscht diese eine Zeile auf die Folgeseite. Und das nennt man in der Textsatzsprache Hurenkind.

[7:02] Das Gegenteil, der Schusterjunge ist, wenn ich einen Absatz auf einer Seite gerade noch beginne, aber nur die erste Zeile dieses Absatzes steht am Ende der Seite und der Rest des Absatzes dann auf der Folgeseite. Das ist dann ein Schusterjunge. Und diese beiden Dinge solltet ihr auf jeden Fall vermeiden. Das ist absolut unschön.

[7:19] Da gibt es in Word eine entsprechende Einstellung. Word macht das zum Beispiel schon automatisch, dass es diese Hurenkinder und Schusterjungen vermeidet. In LaTeX muss man mit einer kleinen Einstellung dafür sorgen, dass das auch nicht passiert. Das sind Dinge, die sind einfach typografisch unschön und die würde ich auf jeden Fall vermeiden.

[7:35] Das Gleiche gilt übrigens auch, wenn ihr Überschriften habt. Man fängt also niemals mit einer Überschrift auf einer Seite an und der Inhalt kommt dann erst auf der Folgeseite. So eine Überschrift 3 steht ganz unten alleine auf der Seite und der Absatz erst auf der Folgeseite. Das geht gar nicht. Habe ich aber schon mehrfach gesehen. Bitte achtet darauf, dass ihr sowas nicht macht. Das ist einfach nicht schön.

[7:54] Wenn wir schon bei den Absätzen sind, dann noch der letzte Tipp zum Seitenstil. Achtet darauf, dass eure Absätze deutlich voneinander abgesetzt werden. Zum Beispiel mit einem vertikalen Abstand. In Word ist das, glaube ich, in der Standardformatvorlage schon so definiert, dass man eine halbe Zeile Abstand oder sogar eine ganze Zeile zwischen einzelnen Absätzen hat. In LaTeX ist es standardmäßig eingerückt.

[8:14] Wenn ihr ein deutsches Format benutzt, dann muss man das einmal umstellen, dass ihr letztendlich einen vertikalen Abstand dazwischen packt. Aber die meisten deutschen LaTeX-Klassen, insbesondere auch die, die ich für meine Vorlage benutze, die ich auch in den Shownotes wieder, wie gehabt, verlinken werde, die kann man so konfigurieren, dass zwischen den Absätzen eben ein vertikaler Absatz ist. Und das würde ich auf jeden Fall machen, denn dann kann man auch die Absätze klar voneinander trennen und weiß, wo der eine Gedankengang aufhört und der nächste anfängt. Das würde ich auf jeden Fall begrüßen.

[8:44] Gut, das waren jetzt ein paar Tipps zum Seitenstil. Dann kommen wir jetzt zum eigentlichen Text, den ihr ja auch noch schreibt. Da ist mein erster Tipp. Achtet unbedingt auf die Vorgaben eurer IHK. Einige IHKen machen detaillierte Vorgaben, wie der Text auszusehen hat bezüglich der Schriftgröße, wo die Seitenzahl platziert werden muss und wie die gesetzt sein müssen, welche Schriftart ihr benutzen müsst und so weiter und so fort. Wenn ihr solche Vorgaben habt, dann berücksichtigt die natürlich auf jeden Fall.

[9:11] Alles, was ich jetzt hier heute erzähle, ist im Prinzip hinfällig, wenn eure IHK euch andere Vorgaben macht. Also schaut genau auf das Formblatt, das ihr vielleicht von der IHK bekommt, wo draufsteht, wie ihr euren Text zu formatieren habt und haltet euch daran. Alles andere ist dann fahrlässig, dann werden euch gegebenenfalls Punkte abgezogen wegen Formfehler, die einfach nicht nötig sind. Ihr seid alle Informatiker, ihr wisst, wie man einen Text zu formatieren hat und müsstet das auch hinbekommen, wenn ihr klare Vorgaben habt, den Text dann so zu gestalten. Also sorgt dafür, dass das passt.

[9:42] Mein erster Tipp, der dann nach diesen Vorgaben kommt, ist, verwendet eine einheitliche Schriftart. Ich habe schon ganz viele Dokumentationen gesehen, wo die Überschriften und der Text und dann noch bestimmte Fachbegriffe im Text alle mit unterschiedlichen Schriftarten gesetzt werden. Das ist gruselig, das macht man nicht. Achtet darauf, dass ihr vernünftig eine einheitliche Schriftart benutzt. In Word ist es sogar so, dass für Überschriften und Fließtext unterschiedliche Schriftarten verwendet werden.

[10:07] Übrigens genau falschrum, so als kleinen Exkurs. Normalerweise benutzt man für den Fließtext nämlich Serifenschriften, also diese Schriften, die so kleine Schlängelchen an den Buchstaben haben. Die sind dazu da, dass das Auge die Zeile besser finden kann und schneller und besser und weniger ermüdend lesen kann.

[10:27] In Word ist es genau falschrum, da wird nämlich für die Überschrift eine Schriftart benutzt, die Serifen hat und für den Fließtext eine Schriftart, die keine Serifen hat. Wenn ihr also ein bisschen typografisch fit seid, dann solltet ihr als erstes das umstellen, denn für den Fließtext ist es absolut sinnvoll, eine Serifenschrift zu benutzen.

[10:44] Die klassische Serifenschrift, die ihr bestimmt auch alle kennt, ist die Times New Roman. Das wäre etwas für den Fließtext. Eine Nicht-Serifenschrift, die bekannte, die auch unter Windows und allen anderen Betriebssystemen verfügbar ist, ist die Arial. Die Arial sollte man nicht für den Fließtext benutzen, eben weil sie keine Serifen hat.

[11:01] In Microsoft Word heißen die Schriftarten Cambria und Calibri. Ich weiß immer jetzt nicht auswendig, welche für die Überschrift und welche für den Text verwendet wird. Auf jeden Fall ist es wie gesagt genau falschrum. Also achtet darauf, dass euer Text in Serifenschrift gesetzt ist und nicht in Serifenloserschrift.

[11:18] Als nächstes solltet ihr darauf achten, dass euer Text im Blocksatz gesetzt ist. Ich sage es nochmal explizit, weil ich schon so viele Dokumentationen gelesen habe, wo das nicht der Fall ist. Ihr kennt die Standardeinstellung in Word. Das ist zum Beispiel der Flattersatz, der linksbündige Flattersatz. Flattersatz deswegen, weil dann auf der rechten Seite die Zeilen unterschiedlich breit sind.

[11:38] Und das geht gar nicht. Das kann das Auge ganz schwer verarbeiten. Wenn jede Zeile unterschiedlich breit ist, muss das Auge immer eine unterschiedliche Strecke bis zur linken nächsten Zeile zurücklegen. Und dann vertut man sich ganz oft in der Zeile und es ist insgesamt schwieriger fürs Auge, die Zeile zu finden.

[11:53] Deswegen benutzt unbedingt Blocksatz. Aber wenn ihr Blocksatz nutzt, gleich der nächste Tipp, aktiviert auch unbedingt die Silbentrennung. Denn wenn ihr die Silbentrennung nicht aktiviert, dann ist es so, dass beim Blocksatz Word zum Beispiel ganz häufig riesengroße Leerräume zwischen die Wörter einfügt, damit eben die Spalten links und rechts untereinander stehen.

[12:13] Und wenn ihr die Silbentrennung aktiviert, dann kann Word bei langen Wörtern am Ende natürlich auch Bindestriche einfügen und so diese riesengroßen Leerräume vermeiden. Das ist nämlich auch völlig kontraproduktiv, ist auch sehr schwer zu lesen und sieht einfach hässlich aus. Also, beides geht eigentlich nur zusammen. Blocksatz aktivieren, Silbentrennung aktivieren, damit der Text vernünftig lesbar ist.

[12:34] Nächster Tipp ist dann, geht möglichst sparsam mit Hervorhebungen um. Ihr könnt nicht allzu viele Hervorhebungen nutzen in eurem Text. Von Unterstreichungen zum Beispiel rate ich komplett ab. Da denkt man heute eher, das ist ein Link, wo ich draufklicken kann. Unterstreichen würde ich heute in keinem Fließtext mehr irgendwas.

[12:50] Genauso wenig hat man früher mal benutzt, das Sperren von Wörtern, also Leerzeichen zwischen die Buchstaben einzufügen. Das würde ich auch auf keinen Fall mehr machen. Das hat man früher mal gemacht bei einer Schreibmaschine. Aber heutzutage ist das kontraproduktiv, weil die Textverarbeitung dann die einzelnen Buchstaben gar nicht mehr als zusammenhängendes Wort erkennt und zum Beispiel rot unterschlängelt und solche Sachen. Also, auf keinen Fall.

[13:09] Letztlich bleiben netto noch übrig, Kursiv setzen und Fett setzen. Und das war es im Prinzip auch schon. Unterschiedliche Farben, unterschiedliche Schriftarten würde ich komplett von abraten. Das sieht unschön aus. Und außerdem, wenn die Prüfer sich die Dokumentation ausdrucken, machen sie das vielleicht auf dem Schwarz-Weiß-Drucker, weil es einfach billiger ist. Stellt euch mal vor, ihr habt da 10 Dokumentationen, liegen a 40 Seiten, müsst da ein paar hundert Seiten ausdrucken. Das machen wir vielleicht nicht mit dem Farbdrucker, einfach weil es viel zu teuer ist.

[13:35] Also, verzichtet auf solche Schmankerl. Wenn ihr Kursiv und Fett nutzen könnt und mehr nicht zur Verfügung habt, dann solltet ihr euch natürlich gut überlegen, was ihr wofür benutzt. Und das ist dann gleich auch der nächste Tipp. Wenn ihr Sachen hervorheben wollt, dann achtet darauf, dass ihr das einheitlich macht.

[13:52] Also, wenn ihr zum Beispiel alle Fachbegriffe, die ihr erklärt oder so, Kursiv setzen wollt, dann achtet darauf, dass alle Fachbegriffe Kursiv gesetzt sind und nicht mal Fett mal Kursiv. Denn dann frage ich mich immer als Prüfer, warum ist das jetzt so gesetzt und nicht anders? Ich will eine Einheitlichkeit haben.

[14:09] Und ich glaube, das ist auch ein ganz wichtiger allgemeiner Tipp. Eure Dokumentation muss einfach ein einheitliches Erscheinungsbild haben. Es ist zum Beispiel völlig bescheuert, wenn eine von 15 Seiten die Seitenzahl anstatt links auf einmal rechts stehen hat. Solche Sachen, die gehen einfach nicht.

[14:24] Und genauso ist es hier im Text. Wenn ich also irgendwelche Fachbegriffe, was auch immer, Klassennamen, Entitätennamen oder wie auch immer, alle Kursiv setze und dann vergesse ich mal eine oder mache eine Fett, dann frage ich mich als Prüfer, was ist jetzt der Sinn dahinter? Ich unterstelle den Prüflingen ja immer, dass sie das, was sie tun, auch mit Bedacht tun und schon wissen, warum.

[14:44] Und ich überlege dann, warum ist jetzt der eine Begriff anders gesetzt? Das muss ja irgendeinen Grund haben. Und wenn ich den dann nicht offensichtlich erkenne, muss ich irgendwie den Schluss ziehen, dass es wohl ein Fehler ist, also schlampige Arbeit war. Und das müsste dann in letzter Konsequenz zu einem Punktabzug führen. Also achtet drauf, dass eure Formatierungen einheitlich sind.

[15:04] Das könnt ihr, wenn ihr eine vernünftige Textverarbeitung benutzt, wie zum Beispiel LaTeX, mit semantischen Befehlen machen. Ich würde zum Beispiel in meiner Projektdokumentation Befehle anlegen für Klasse, Methode, Entität, Use Case, was auch immer.

[15:20] Alle diese Dinge, die ihr in eurem Text referenziert und nennt eventuell, die sollten so eine semantische Auszeichnung bekommen, damit ihr dann irgendwo an einer Stelle sagen könnt, alle Entitäten Fett, alle Klassennamen Kursiv und nicht manuell im Text Fett und Kursiv und unterstrichen und farbig oder weiß der Geier was, was ihr eigentlich gar nicht benutzen sollt, manuell vergeben.

[15:41] Und nachher sagt ihr dann, hätte ich es mal doch Fett gemacht und ihr müsst manuell 37 Stellen ändern. Ich glaube, das wollen wir nicht. Ich hoffe, ihr wisst, wie man mit einer Textverarbeitung vernünftig umgeht. Selbst in Word geht das. Da legt ihr eine Textformatvorlage an, die ihr dann entsprechend benennt und dann könnt ihr auch mit drei Klicks alle Fachbegriffe Fett machen, wenn sie vorher Kursiv waren und umgekehrt.

[16:00] Also benutzt semantische Textverarbeitung. Achtet darauf, dass alle einheitlichen Begrifflichkeiten auch einheitlich formatiert werden.

[16:11] Grundsätzlich solltet ihr aber relativ sparsam mit Hervorhebungen umgehen, einfach weil der Text sonst ein bisschen aussieht wie wild zusammengebastelt. Hier nochmal was Fett und da nochmal Kursiv und hier nochmal irgendwie eine ganz andere Darstellungsweise.

[16:25] Es ist ja immerhin ein vernünftiger, technischer Dokumentationstext und da wollen wir hier nicht lustige Formatierungen reinbauen, sondern es muss auch den Sinn unterstreichen. Also wenn ihr zum Beispiel Fachbegriffe benutzt oder Klassennamen, dann ist es ja einfach sinnvoll, wenn man die anders setzt, einfach um zu erkennen, aha, es geht hier eben um die Klasse Manager und nicht um die Entität Manager.

[16:46] Wenn es zum Beispiel gleichnamige Dinge gibt in eurem Text, das will ich halt auseinanderhalten können. Dafür ist es auch sinnvoll. Aber es soll halt nicht heißen, dass alle Klassennamen rot und alle Entitäten grün dargestellt werden. Nicht übertreiben.

[17:01] Gut, wenn wir schon bei solchen Sachen sind wie Klassennamen und Entitäten, da würde ich noch einen konkreten Tipp geben. Diese Dinge würde ich nämlich in nicht-proportionaler Schrift setzen. Das heißt, kennt ihr wahrscheinlich alle sowas wie Carrier New. Das sind also die Schriften, wo jedes Zeichen die gleiche Breite hat. Da ist also das i genauso breit wie ein m.

[17:19] Wenn ihr euch eine Proportional-Schrift anschaut, ist das nicht der Fall. Da ist das i ungefähr ein Drittel der Breite vom m. Denn das ist ja nun mal, wenn ich es auf dem Blatt Papier malen würde, wäre es auch nur ein Strich und das m wären halt mindestens mal drei Striche. Muss also ein bisschen breiter sein.

[17:34] Aber gerade bei Code, bei Klassennamen, bei Kommandozeilenbefehlen, die ich eintippen muss oder eben bei Entitätsnamen oder was auch immer, da will ich eigentlich kennlich machen, dass es eben sowas ist wie Code. Und Code sollte immer ein nicht-proportionaler Schriftgesetz sein. Kennt ihr selber aus der Programmierung. Die Zeilen sollen vernünftig untereinander stehen, die geschweifelten Klammern sollen untereinander stehen und da will ich jetzt also nicht mit proportionaler Schrift arbeiten und jede Zeile sieht unterschiedlich aus. Das ist nicht Ziel des Ganzen.

[18:03] Also achtet drauf, dass diese Teile in nicht-proportionaler Schrift gesetzt werden. Dann habt ihr schon ein drittes Stilmittel zusätzlich zu Fett und Kursiv, also nicht-proportionaler Schrift. Und das würde ich benutzen für alle technischen Begriffe.

[18:15] Zuletzt noch ein konkreter Tipp, das sehe ich auch in ganz vielen Projektdokumentationen, dass Prüflinge zum hervorheben von Begriffen Anführungszeichen benutzen.

[18:24] Da wird dann zum Beispiel, ich nehme mal das Beispiel Klassenname, da wird jede Klasse in Anführungszeichen gesetzt. Und das ist einfach gruselig. Das macht man einfach nicht.

[18:33] Vor allen Dingen überlegt euch mal, wenn ihr das ändern wollt, wenn ihr dann sagt, okay, die Anführungszeichen gefallen mir nicht mehr, ich will jetzt die Anführungszeichen raushaben und stattdessen das Zeug kursiv machen, das kriegt ihr gar nicht automatisch hin.

[18:42] Denn die Anführungszeichen sind ja wirklich Textbestandteile, die ihr eingeben müsst. Da könnt ihr nicht mal eben auf eine Formatvorlage klicken und sagen, mach mal die Anführungszeichen weg, sondern das ist wirklich Text, der da drin steht, den müsst ihr manuell nachher wieder rauslöschen.

[18:55] Und noch schlimmer ist dann, wenn die Anführungszeichen auch noch nicht typografisch korrekt sind. Das heißt zum Beispiel im deutschen Text die Anführungszeichen alle oben stehen. So was geht auch gar nicht.

[19:03] Wir schreiben eine deutsche Dokumentation, da erwarte ich auch korrekte typografische deutsche Anführungszeichen und die fangen in Deutschland unten links an und hören oben rechts auf und stehen nicht beide oben. Das wäre englischer Text.

[19:18] Gut, damit wäre ich jetzt meine Liste der Texthinweise durch. Dann gehen wir doch zum letzten Punkt, nämlich den Artefakten.

[19:26] Die Artefakte, das hatte ich beim letzten Mal schon erwähnt, gehören eigentlich ausnahmslos in den Anhang. Meine Regel wäre, alles was größer ist als eine halbe Seite, muss auf jeden Fall in den Anhang.

[19:37] Bei allen anderen Artefakten könnte man drüber reden, ich würde, um auf Nummer sicher zu gehen, einfach alles in den Anhang packen.

[19:43] Überlegt euch die 15 Seiten, die ihr zur Verfügung habt, das ist relativ wenig, um ein 70-stündiges Projekt zu dokumentieren.

[19:50] Von daher, wenn ihr dann auch noch 3, 4 große Tabellen oder Abbildungen in eurem Text habt, ja, der ganze Platz geht euch ja verloren für den eigentlichen Inhalt.

[19:57] Von daher, meine Empfehlung, packt einfach gleich alles in den Anhang.

[20:00] dann habt ihr wenigstens keinen Platz für den wichtigen Inhalt verschenkt.

[20:04] Wichtig bei den Artefakten ist, dass ihr die alle beschriftet und auch im Text

[20:09] referenziert.

[20:10] Eine ganz häufige Kritik, die wir Prüfer an den Dokumentationen haben, ist,

[20:14] dass der Anhang voll gestopft wird mit irgendwelchen Artefakten, aber im

[20:17] Fließtext ist da nicht mal ansatzweise die Rede von.

[20:20] Das heißt, wir lesen uns den Text vorne durch und denken, ach ja, das ist ja eine tolle Sache,

[20:24] schlagen den Anhang auf, auf einmal sind da Use-Case-Diagramme und Klassenmodelle

[20:28] und weiß der Geier was nicht alles, aber davon wurde im Text nicht ein Wort

[20:33] erwähnt und das geht nicht. Alle Artefakte in eurer Dokumentation müssen

[20:37] vernünftig referenziert sein. Bedeutet im Klartext,

[20:40] jedes Artefakt braucht eine Unterschrift oder Überschrift, je nachdem wo ihr das

[20:44] platziert,

[20:46] eine Durchnummerierung,

[20:47] es muss ja nachher auch ein entsprechendes Verzeichnis vorne geben,

[20:50] zum Beispiel ein Abbildungs- oder Tabellenverzeichnis,

[20:52] und

[20:53] jedes Artefakt muss im Fließtext referenziert werden. Was bedeutet das?

[20:57] Irgendwo im Text steht sowas wie

[20:59] wie in Abbildung 1 zu sehen…

[21:02] Das heißt, ihr könnt nicht einfach sowas schreiben wie

[21:06] in meinem ER-Modell habe ich das und das gemacht und dann platziert ihr einfach

[21:10] das Bild des ER-Modells da, sondern ihr müsst das referenzieren. Im Text muss

[21:13] auftauchen,

[21:14] wie im ER-Modell in Abbildung 7 zu sehen ist

[21:18] und dann weitermachen.

[21:19] Das erwarte ich, dass das bei allen Artefakten gegeben ist.

[21:23] Es darf also kein Artefakt geben,

[21:25] was irgendwie völlig losgelöst ohne Kontext im Fließtext

[21:29] auftaucht. Das ist nicht erlaubt.

[21:33] Beziehungsweise, ihr könnt das gerne machen,

[21:34] würde in meinem Fall aber zu Punktabzug führen, sagen wir so.

[21:38] Gut, wenn wir dann zu den verschiedenen Diagrammen kommen, die ihr ja absolut

[21:42] auch in eurer Projektdokumentation unterbringen müsst, keine Frage, dann

[21:46] achtet doch darauf, dass ihr skalierbare Grafikformate verwendet.

[21:50] Wenn ich

[21:51] eine Dokumentation ausdrucke

[21:53] auf einem vernünftigen Drucker und ich erkenne schon, dass die Grafiken

[21:56] pixellig sind,

[21:57] dann weiß ich, da wurden mal wieder irgendwelche,

[22:00] am besten noch komprimierten Bitmaps oder so, in die Dokumentation reingepackt

[22:04] und das passt natürlich nicht zu dem schönen, klaren Schriftbild der

[22:08] perfekt skalierten

[22:09] Schrift darüber. Ja, und dann sehe ich gleich, oh, das sind Qualitätsunterschiede,

[22:13] das sieht einfach hässlich aus, das muss nicht sein.

[22:15] Heute ist es so einfach, mit verschiedenster Grafiksoftware Vektorformate

[22:19] zu exportieren,

[22:21] sei es zum Beispiel ein SVG oder ein EPS oder was auch immer. Es gibt so viele

[22:25] verschiedene Formate, die ihr da nutzen könnt

[22:27] und die tragen dazu bei, dass eure Dokumentation perfekt skaliert, auch

[22:31] wenn ich sie auf einem vernünftigen Drucker ausdrucke. Oder wenn ich sie als PDF

[22:35] mir angucke, was ja auch bei vielen IRKn der Fall ist, und ich zoome da mal rein,

[22:39] weil ich was nicht lesen kann, und auf einmal wird alles pixellig anstatt

[22:42] scharf und lesbar.

[22:43] Das geht auch gar nicht.

[22:45] Achtet sowieso darauf, dass eure Artefakte vernünftig lesbar sind, ja, ich

[22:49] weiß gar nicht, ob ich das nochmal extra erwähnen muss, ich glaube aber schon,

[22:52] denn ab und zu

[22:53] habe ich da manchmal Grafiken drin, zum Beispiel ER-Modelle oder Klassendiagramme,

[22:57] da kann ich die simpelsten Bestriftungen nicht lesen, weil die wirklich schon

[23:00] pixellig sind oder so klein skaliert, dass ich es überhaupt nicht mehr erkennen kann.

[23:04] Und das geht natürlich gar nicht, dann kann ich die Inhalte nicht bewerten,

[23:06] weil ich gar nicht weiß, ob es richtig ist, denn ich kann es ja nicht lesen.

[23:09] Also, wenn ihr zum Beispiel Diagramme zeichnet und so weiter, normalerweise die

[23:13] Programme, die ihr benutzt, werden es in irgendeiner Form anbieten, eine

[23:16] skalierbare

[23:18] Grafik zu exportieren und die benutzt ihr dann auch für eure Dokumentation und

[23:22] nicht JPEG, PNG oder GIF oder was auch immer.

[23:25] Das skaliert nicht, das ist hässlich, pixellig, wenn ich das größer mache und

[23:29] eventuell kann ich es gar nicht erkennen, was drauf abgebildet ist.

[23:33] Wenn ihr dann als weiteren wichtigen Bestandteil eurer Dokumentation sicherlich

[23:37] auch Quelltext in die Dokumentation packt,

[23:40] dann achtet doch darauf, dass der vernünftig gesetzt ist und zwar in

[23:43] Nicht-Proportional-Schrift, das hatte ich eben schon erwähnt, aber der kann auch

[23:46] ruhig gehighlighted werden.

[23:48] Das heißt,

[23:49] hier könnte man tatsächlich dann mal eine Ausnahme machen und den Text auch farbig

[23:52] setzen oder zumindest von einem Highlighter irgendwie fett oder Kursiv

[23:56] oder sogar unterstrichen, wenn es zum Beispiel eine statische Methode ist,

[24:00] darstellen lassen, damit man diesen Text besser verstehen kann.

[24:03] Wenn ich ein Quelltext-Beispiel habe und der ist in Proportional-Schrift

[24:07] gesetzt ohne Hervorhebung, das ist dann doch schon sehr schwierig, den

[24:11] zu verstehen, denn man ist es als Entwickler halt gewöhnt,

[24:15] dass der Quelltext von der IDE zum Beispiel gehighlighted wird oder

[24:18] entsprechend schön umgebrochen wird und klar untereinander steht.

[24:21] Und wenn ich dann auf einmal in so einer gedruckten Dokumentation

[24:24] Quelltext wie Prosa lesen soll, dann wird das schon sehr schwierig, das

[24:28] nachzuvollziehen.

[24:29] Also von daher dürft ihr hier ruhig eine Ausnahme machen.

[24:32] Einige Prüflinge machen dann sogar Screenshots aus der IDE, die das ja schon

[24:36] super highlighted und packen die dann in die Doku.

[24:38] Hier müsst ihr aber dran denken, Screenshots sind nicht skalierbar. Das sind

[24:41] immer Bitmap-Grafiken.

[24:43] Das heißt, wenn ich die dann groß mache, werden sie pixellig und ich kann

[24:46] nichts mehr erkennen.

[24:47] Am schönsten wäre es, wenn eure Textverarbeitung den Quelltext

[24:49] highlighten kann.

[24:51] LaTeX zum Beispiel kann das sehr gut. Da gibt es ein Listings-Package, da

[24:55] könnt ihr sogar selber definieren, wie die Highlights stattfinden sollen. Da

[24:59] gibt es dann sogar Zeilennummern daneben und so weiter.

[25:01] Und ihr könnt in LaTeX zum Beispiel auch eure Listings direkt aus den

[25:04] Quellcodedateien inkludieren. Ihr könnt einfach sagen,

[25:06] nehmt die Datei unter Pfad XY und zeigt mir an Zeile 37 bis 59

[25:12] und dann ist das Schuppdiwupp schon in eurer Dokumentation drin, ohne dass

[25:16] ihr das per Hand irgendwo rein friemeln müsst.

[25:19] Mit Word geht das sicherlich auch irgendwie. Fragt mich nicht, wie. Das habe

[25:22] ich noch nie gemacht. Aber wichtig wäre, dass der Prüfer diesen Quellcode

[25:26] vernünftig lesen kann.

[25:27] Ihr kennt das vielleicht auch bei der Vorbereitung für die schriftliche Prüfung.

[25:30] Wenn ihr Quelltext auf Papier schreiben müsst, das ist schon schwierig genug.

[25:33] Und wenn wir es jetzt lesen müssen, ist das auch nicht so einfach wie am

[25:36] Bildschirm.

[25:37] Und von daher, unterstützt uns doch bitte und formatiert den Quelltext, so wie

[25:41] er vielleicht auch in der IDI aussehen würde, damit man ihn eben vernünftig

[25:44] verstehen kann.

[25:46] Wenn wir schon beim Stichwort Quelltext sind und auch bei Screenshots, nochmal

[25:51] letzter Tipp für heute. Achtet drauf, dass nur interessante Ausschnitte zu

[25:55] sehen sind. Das habe ich, glaube ich, für den Quelltext schon 97 mal erwähnt.

[25:59] Zeigt mir nicht seitenweise Getter, Setter, sondern zeigt mir interessante

[26:03] Ausschnitte.

[26:04] Und genau das gleiche gilt auch für Screenshots. Ich habe schon in mehreren

[26:07] Dokumentationen dann Screenshots von dem fertigen Programm gesehen, wo aber nicht

[26:10] nur das Programmfenster abgefotografiert wurde, sondern der gesamte Desktop mit

[26:14] Startleiste und noch der Hälfte vom Explorer-Fenster im Hintergrund und so

[26:18] weiter.

[26:19] Das ist völlig unnötig und nicht nur unnötig, es nimmt auch Platz weg und ich

[26:23] kann den eigentlichen wichtigen Inhalt, nämlich euer Programm, nicht vernünftig

[26:26] erkennen, weil so viel unnötiger Kram drum herum steht.

[26:30] Also bitte, ich hoffe, dass jeder von euch ein rudimentäres

[26:33] Bildbearbeitungswerkzeug, wie zum Beispiel Irfenview oder Paint.net oder was auch

[26:38] immer, bedienen kann und die wichtigen Inhalte ausschneiden kann und nur die in

[26:43] die Dokumentation packt.

[26:44] Das kann ich eigentlich von so einem fertigen Anwendungsentwickler erwarten,

[26:46] dass das möglich ist.

[26:47] Und ihr müsst nicht mit Druck und Steuerung V in Word gesamte Windows

[26:53] Screenshots einfügen.

[26:54] Das ist völlig unnötig, raubt nur Platz und trägt nicht zu Lesbarkeit bei.

[26:59] So, damit wäre ich für heute durch.

[27:01] Das waren meine Tipps zum Layout der Projektdokumentation.

[27:05] Ich hoffe, für den einen oder anderen war noch was Interessantes dabei.

[27:09] Ich habe so ein paar Sachen aufgeschrieben, die ich einfach in den letzten Jahren in den

[27:13] Dokumentationen, die ich gelesen habe, immer wieder gesehen habe und die mich einfach

[27:16] immer tierisch annerven.

[27:18] Ich bin auch ein bisschen penibel, sage ich mal, wenn es um die Textgestaltung geht.

[27:23] Ich habe da auch so ein bisschen ein Fable für und ich achte auf solche Sachen, ob man

[27:27] zum Beispiel den richtigen Bindestrich benutzt, ob man einen Bindestrich oder einen

[27:30] Gedankenstrich benutzt.

[27:30] Das ist tatsächlich ein Unterschied, so als kleiner Exkurs.

[27:33] Wer das nicht weiß, der Bindestrich ist nämlich ein bisschen kürzer als der Gedankenstrich.

[27:37] In LaTeX gibt es deswegen sogar extra einen unterschiedlichen Befehl, um diesen

[27:41] Gedankenstrich zu setzen.

[27:42] Das sind nämlich zwei Minuszeichen anstatt einem und solche Sachen fallen mir einfach

[27:47] auf. Und ich weiß nicht, ob es noch viele andere Bücher gibt, denen das auch auffällt.

[27:51] Mir fällt es jedenfalls auf.

[27:52] Deswegen heute noch mal ein paar detaillierte Tipps, sehr typografisch korrekt.

[27:58] Aber ich glaube, wenn ihr mehr Arbeit in die Dokumentation steckt und sie perfekter

[28:03] macht, als sie sein müsste, ist das sicherlich nicht zu eurem Nachteil.

[28:07] Von daher habe ich einfach mal alles heute zusammengetragen, was mir so aufgefallen ist.

[28:12] Ich hoffe, ihr konntet heute einige interessante Punkte für euch mitnehmen.

[28:17] Wenn das so ist oder wenn ich noch was vergessen habe, das kann ja auch gut sein.

[28:21] Dann schreibt mir doch einfach Feedback zur Episode.

[28:23] Ihr findet wie immer die Shownotes zur heutigen 31.

[28:27] Episode unter anwendungsentwicklerpodcast.de

[28:30] slash 31.

[28:32] Ihr könnt mir auch gerne eine Mail schicken an mail at anwendungsentwicklerpodcast.de

[28:37] und am meisten freuen würde ich mich über ein Review bei iTunes unter

[28:41] anwendungsentwicklerpodcast.de slash iTunes.

[28:44] Das trägt dazu bei, dass der Podcast noch etwas bekannter wird und vielleicht noch mehr

[28:49] Prüflinge in den Genuss meiner Tipps kommen.

[28:52] Wenn ihr ansonsten irgendwelche anderen Fragen rund um die Ausbildung habt, dann

[28:56] fragt mich gerne.

[28:57] Ich beantworte die Sachen auch gerne in meinem Podcast oder auf der Website in einem

[29:01] ausführlichen Artikel.

[29:02] Also wenn ihr irgendwas wissen wollt, dann stellt mir ruhig Fragen.

[29:08] Zum Abschluss der Episode wie immer der Hinweis auf meinen Newsletter unter

[29:12] anwendungsentwicklerpodcast.de slash Newsletter könnt ihr euch mit eurer

[29:17] E-Mail-Adresse anmelden.

[29:18] Ihr könnt euch auch jederzeit übrigens wieder abmelden, wenn euch die Inhalte nicht

[29:21] mehr gefallen. Aber als Dankeschön bekommt ihr auch sofort Zugriff auf meine

[29:25] Checklisten und passend zu dieser Episode heute insbesondere auch die Checkliste zur

[29:30] Projektdokumentation.

[29:31] Da stehen diese Tipps, die ich heute gegeben habe, auch nochmal schwarz auf weiß

[29:35] zum Durchgucken drin.

[29:37] Bevor ihr eure Projektdokumentation abgebt, könnt ihr also durchaus die Checkliste mal

[29:41] durchgehen und gucken, ob ihr noch irgendwas vergessen habt oder irgendwas übersehen

[29:44] habt. Mindestens die Sachen der heutigen Episode stehen da drin.

[29:48] Und zusätzlich auch noch ein paar mehr Sachen, nicht nur was die Typografie und den

[29:51] Seitenstil angeht, sondern auch die Inhalte nochmal, die Projektphasen und so weiter.

[29:55] Da stehen insgesamt schon über 100 Punkte drauf auf der Checkliste und die wird auch

[29:58] regelmäßig erweitert, wenn was dazu kommt.

[30:00] Von daher, wenn ihr mögt, tragt euch in den Newsletter ein.

[30:03] Zusätzlich bekommt ihr auch meine Links der Woche immer schon am Montag vorab und nicht

[30:07] erst am Freitag, wenn sie normalerweise im Blog erscheinen.

[30:11] Damit sage ich vielen Dank fürs Zuhören und bis zum nächsten Mal.

[30:16] Tschüss!