Um die sinnvolle Platzierung von Artefakten in der Projektdokumentation geht es in der zehnten Episode der Shorts des IT-Berufe-Podcasts. Inhalt Ich empfehle dir für die Projektdokumentation als klare Daumenregel, Artefakte wie Diagramme, Tabellen, Code, Screenshots oder Berechnungen in den Anhang zu packen – besonders dann, wenn sie größer als eine halbe Seite sind. Im Fließtext sollte stattdessen stehen, warum du ein Artefakt erstellt hast, wie es dir im Projekt geholfen hat und was du daraus abgeleitet hast. Nur kleine, direkt erklärungsbedürftige Artefakte können aus Gründen der Lesbarkeit ausnahmsweise in den Fließtext. Was ich mit Artefakten meine Mit Artefakten sind alle Bestandteile der Projektdokumentation gemeint, die kein eigentlicher Fließtext sind. Dazu zählen zum Beispiel: Diagramme wie UML-Diagramme oder ER-Modelle Tabellen, etwa für Kosten oder Zeitplanung Code Netzwerkpläne Testprotokolle Berechnungen und Formeln Screenshots und Fotos Zentrale Daumenregel Meine Empfehlung ist klar: Alle Artefakte gehören grundsätzlich in den Anhang. Alles, was größer als eine halbe Seite ist, sollte auf jeden Fall in den Anhang. Nur wenige Ausnahmen sprechen dafür, ein Artefakt direkt im Fließtext zu platzieren. Warum Artefakte besser in den Anhang gehören Der wichtigste Grund ist die begrenzte Seitenzahl für den Fließtext. Viele IHKs machen dafür klare Vorgaben, zum Beispiel 15 Seiten Fließtext und 25 Seiten Anhang. Diese Vorgaben unterscheiden sich aber je nach IHK teilweise deutlich. Wichtig ist deshalb: Prüfe immer die konkreten Vorgaben deiner IHK. Verlasse dich nicht pauschal auf Angaben aus dem Internet. Wenn du Artefakte in den Fließtext einbaust, verbrauchen sie dort Platz. Dadurch bleibt weniger Raum für erklärenden Inhalt, der in der Bewertung oft entscheidend ist. Eine Seite Klassendiagramm im Fließtext ist dann eben keine Seite Fließtext mehr. Seitenzahl ist nicht das eigentliche Problem Entscheidend ist nicht, ob am Ende 14 oder 15 Seiten dort stehen. Entscheidend ist, ob wichtige Inhalte fehlen. Wenn zum Beispiel in einem Projekt ein bestimmtes Artefakt sinnvoll oder zu erwarten ist, dann fehlt ohne dieses Artefakt möglicherweise ein relevanter Inhalt. Umgekehrt hilft es auch nicht, die maximale Seitenzahl auszuschöpfen, wenn dabei inhaltlich etwas Wichtiges fehlt. Die Seitenzahl ist also nur ein Rahmen. Bewertet werden am Ende die Inhalte, nicht bloß die Zahl auf der letzten Seite. Ausnahme: Lesbarkeit Der wichtigste Grund, ein Artefakt doch im Fließtext zu platzieren, ist die Lesbarkeit. Das kann sinnvoll sein, wenn: ein Artefakt sehr erklärungsbedürftig ist der zugehörige Text direkt daneben stehen sollte ständiges Blättern oder Springen zwischen Text und Anhang das Verständnis erschwert Beispiele dafür können sein: eine kurze, erklärungsintensive Code-Stelle eine kleine Berechnung oder Formel eine kompakte Kostenberechnung eine grobe Zeitplanung eine Amortisationsrechnung Dabei bleibt die zweite Daumenregel bestehen: Ist das Artefakt größer als eine halbe Seite, gehört es trotzdem in den Anhang. Denn wenn Erklärung und Artefakt ohnehin nicht mehr gemeinsam auf eine Seite passen, geht der Vorteil für die Lesbarkeit wieder verloren. Artefakte nicht als Seitenfüller verwenden Artefakte sollten nicht dazu dienen, den Fließtext künstlich aufzublähen, wenn dir sonst Inhalt fehlt. Wenn große oder unpassende Artefakte ohne echten Grund im Fließtext stehen, kann das bei der Bewertung als Hinweis gesehen werden, dass dort eigentlich zu wenig sinnvoller Textinhalt vorhanden ist. Solche Artefakte werden inhaltlich nicht als Ersatz für fehlende Erklärungen gewertet. Wichtig dabei: Es gibt nicht automatisch Punktabzug wegen einer bestimmten Seitenzahl. Punktabzug entsteht dann, wenn dadurch erkennbare inhaltliche Lücken bleiben. Artefakte haben einen Zweck Eine Projektdokumentation sollte nicht aus einer bloßen Sammlung von Artefakten bestehen. Nicht ausreichend ist zum Beispiel: Überschrift ein Satz wie "Ich habe ein UML-Diagramm erstellt, siehe Anhang" sonst keine weitere Erklärung Artefakte haben keinen Selbstzweck. Sie sollen zeigen, dass du methodisch gearbeitet hast und dir vor der Umsetzung Gedanken gemacht hast. Beispiele: In der Anwendungsentwicklung helfen Klassendiagramme, ER-Modelle oder Architekturskizzen dabei, die Struktur vor der Implementierung zu planen. In der Systemintegration helfen Netzwerkpläne oder Sicherheitsüberlegungen dabei, Anforderungen und Rahmenbedingungen sauber zu analysieren. Artefakte sollen also nicht nur für die Prüfung da sein, sondern einen praktischen Nutzen im Projekt haben. Was in den Fließtext gehört Im Fließtext sollte stehen: warum du ein Artefakt erstellt hast wie du dabei vorgegangen bist welche Besonderheiten dir dabei aufgefallen sind wie dir das Artefakt im weiteren Verlauf geholfen hat was du darauf aufbauend später gemacht hast Ein gutes Beispiel wäre nicht nur zu schreiben, dass ein Klassendiagramm existiert, sondern zu beschreiben: welche Klassen notwendig waren welche Beziehungen oder Abstraktionen sich ergeben haben welche Erkenntnisse daraus entstanden sind wie das Diagramm später bei der Implementierung geholfen hat Das Artefakt selbst kommt dann in den Anhang, der Kontext und die Einordnung gehören in den Fließtext. Fazit Die Kernaussage ist: Artefakte in den Anhang Erklärungen, Einordnung und Nutzen in den Fließtext Ausnahmen im Fließtext sind nur dann sinnvoll, wenn kleine Artefakte direkt zum Verständnis beitragen. Für fast alles andere gilt: Anhang. So nutzt du sowohl den Fließtext als auch den Anhang sinnvoll aus und zeigst nicht nur Ergebnisse, sondern auch dein methodisches Vorgehen. Links Permalink zu dieser Podcast-Episode RSS-Feed des Podcasts Transkription der gesamten Episode Automatisch erzeugte Transkription der Episode [0:20] Heute geht es mal um eines meiner Lieblingsthemen, wenn ich wieder Projektdokumentation lese und bewerten darf. Und zwar um die Platzierung von Artefakten in der Projektdokumentation. Diesen Begriff Artefakt, den benutze ich ganz häufig im Blog, im Podcast, in meinen Videos. Was ist damit gemeint? Kurz zum Einstieg. Ich meine mit Artefakt alles, was in der Dokumentation oder in deiner Präsentation später auch, was kein Fließtext ist. Also Beispiel Projektdokumentation, irgendwelche Diagramme, UML-Sachen, ER-Modelle, Amortisationsrechnung, wenn du die grafisch machst, aber auch Tabellen, zum Beispiel Kostenaufstellung oder deine Zeitplanung. Code natürlich, wenn du Anwendungsentwicklung machst, irgendwelche Pläne, Netzwerkpläne oder Sonstiges oder ein Testprotokoll oder so. Oder auch wenn du Berechnungen machst, irgendwelche Formeln oder Sachen, die nacheinander berechnet werden, zum Beispiel bei der Amortisationsrechnung. Und selbstverständlich auch Screenshots, wenn du Fotos machst aus der echten Welt, solche Dinge, das sind für mich alles Artefakte. Also Dinge, die kein Text sind, wobei, ja, Code ist Text, okay. Aber ich glaube, du verstehst, worauf ich hinaus will. Fließtext im Verhältnis zu alles andere sind Artefakte. Und ich mache es gerne zum Einstieg nochmal, wie in anderen Episoden auch, so ein Too Long Didn’t Read oder Didn’t Here in diesem Fall. Meine Empfehlung ist, pack alle Artefakte in den Anhang. Es gibt wenig Gründe dafür, Artefakte in deinen Fließtext zu packen. Also du schreibst einen Satz, machst dann ein Artefakt da rein und schreibst dann weiter. [1:48] Daumenregel sollte sein, alles in den Anhang. Und absolute Daumenregel aus meiner Sicht ist, alles was größer ist als eine halbe Seite, auf jeden Fall in den Anhang. So und jetzt gibt es vielleicht ein, zwei kleine Ausnahmen, wo man Artefakte auch in den Fließtext packen sollte oder darf oder vielleicht sogar muss. Da gehen wir gleich nochmal drauf ein. Aber als Daumenregel kannst du schon mal mitnehmen, alle Artefakte in den Anhang, insbesondere wenn sie größer sind als eine halbe Seite. [2:13] So, jetzt gehen wir mal die Details da durch. Warum ist das so? Warum ist das sinnvoll? Also, vielleicht vorweg, die meisten IHK’n machen irgendwelche Vorgaben für deine Projektdokumentation, was die Seitenzahl angeht. Und das sind meistens Maximalforgaben, also zum Beispiel maximal 15 Seiten Fließtext und 25 Seiten Anhang. So ist es zum Beispiel bei der IHK Oldenburg, wo ich beschäftigt bin. Ganz wichtig vorweg, guck dir unbedingt die Vorgaben deiner IHK an. Es gibt nämlich 79 verschiedene in Deutschland und die machen im Zweifel alle unterschiedliche Vorgaben. Also orientier dich nicht an irgendwas, was du im Internet gehört oder gelesen hast, sondern frag bei deiner IHK nach, wo du deine Note nachher bekommst, was die Vorgaben sind. Ich gehe jetzt mal einfach davon aus, dass es 15 Seiten für Fließdecks sind und 25 für Anhang. So ist es bei uns. Aber das kann stark abweichen. Ich habe teilweise Vorgaben gesehen bis 10 Seiten runter plus nochmal 5 im Anhang oder so. Also wirklich deutlich weniger. Es gibt aber auch nach oben Abweichungen. Also guck einfach nach, was gilt für dich und dann orientierst du dich an diesen Zahlen. Ich gehe jetzt mal von den 15 Seiten aus und dann ist es üblicherweise so, dass du deine Seitenzahl maximal ausreizen möchtest. Dafür habe ich auch eine eigene Episode, einen kleinen Short aufgenommen, verlinke ich auch nochmal in den Shownotes, warum ich dann empfehlen würde, die Seitenzahl auszufüllen. Kurz gesagt, was ist, wenn du nicht alles ausfüllst? Kriegst du eine schlechte Note? Ja, dann hast du deine Chancen, die du hättest, halt nicht genutzt. Du hast zu wenig Inhalt geliefert, kriegst dafür einen Punktabzug. Blöd, ja? Also versuch die Seitenzahl auszunutzen und so gut es geht, alles mit sinnvollen Inhalten zu füllen. [3:40] Und dann solltest du, wenn du sinnvolle Inhalte hast, sowas wie Lastenpflichtenheft, UML-Diagramme u