Platzierung von Artefakten in der Projektdokumentation – IT-Berufe-Podcast-Shorts #10

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 und
ich weiß nicht, was du alles erstellen kannst für dein Projekt,
auch dazu ein Hinweis in der verlinkten Episode, solltest du
genug Inhalt haben, um deine Fließtext-Seiten zu füllen, aber
auch um den Anhang zu füllen. Meistens sogar eher für den
Anhang noch mehr, allein schon, wenn du was programmierst.
Code-Beispiele, da kannst du ganz, ganz, ganz, ganz, ganz viel
zeigen und Screenshots und ich weiß nicht mehr. Also
normalerweise solltest du keine Probleme haben, um diese
Seitenzahl zu erreichen. Es sollte eher ein Problem sein,
zusammenzustreichen, um wieder auf die Seitenzahl
runterzukommen, wenn du drüber bist. Das ist meine persönliche
Einstellung. Wenn das nicht geht bei deinem Projekt, hast du
vielleicht ein zu wenig umfangreiches Projekt oder du hast
einfach einen Haufen Artefakte vergessen, die in der Prüfung
möglicherweise erwartet werden, aber dazu auch mehr in einer
anderen Episode. Heute geht es ja darum, wenn du diese ganzen
Inhalte hast, wo packst du sie hin?


[4:32] Und ich würde halt sagen, dass du Fließtext
locker füllen kannst und den Anhang genauso. Und wenn du jetzt
Artefakte in deinen Fließtext packst, dann gehen die ja von der
Seitenzahl für deinen Fließtext ab. Also keine Ahnung, du hast
15 Seiten Fließtext und mittendrin hast du aber eine ganze
Seite Klassendiagramm. Dann hast du natürlich eine Seite
weniger für den Text, weil das Klassendiagramm braucht dir auf,
diese eine Seite. Das heißt, du hast also nicht wirklich 15
Seiten Fließtext, sondern nur 14, weil eine Seite davon ist
halt ein Klassendiagramm.


[5:01] Und das ist ja blöd, weil auf dieser Seite
Fließtext hättest du ja auch noch Inhalte unterbringen können,
die jetzt vermutlich fehlen. Und hier auch nochmal, ich habe es
in einer anderen Episode auch schon gesagt, wenn ich über
Punktabzug oder Notenabzug oder Durchfallen spreche, dann hat
das nie etwas damit zu tun, ob am Ende da 14 oder 15 Seiten
stehen, sondern es hat immer etwas damit zu tun, dass Inhalte
nicht da sind, die erwartet werden. Ja, dass du irgendwas
Wichtiges nicht gezeigt hast. Keine Ahnung, wenn du zum
Beispiel gar kein Klassendiagramm hast oder gar kein Code in
einem Anwendungs-Ermütungsprojekt, würde ich sagen, da fehlt
was, weil das würde ich schon ganz gern sehen. Ja, und da hilft
es auch nicht, wenn du 15 Seiten Fließtext voll ausgereizt
hast, aber du hast trotzdem kein Klassendiagramm gemacht. Und
das ist jetzt nur ein Beispiel. Ja, es ist nicht für jedes
Projekt ein Klassendiagramm sinnvoll. Es ist nur ein Beispiel.
Aber wenn ich es erwarten würde in deinem Projekt, aber du hast
es nicht gemacht und dafür trotzdem 15 Seiten geschrieben, dann
fehlt mir halt trotzdem was. Ja. Und auch wenn du nur 14 hast
und dir fehlt das Klassenlegramm, fehlt mir das Klassenlegramm.
Also bitte, häng dich nicht an dieser Seitenzahl auf und denk
auch nicht, dass die Prüfer dir Punkte abziehen, nur weil du
nicht die richtige Seitenzahl hast.


[6:03] Sondern es geht immer um die jeweils
fehlenden Inhalte. Und deswegen versuchen wir die Seiten
möglichst mit sinnvollen Inhalten zu füllen und dann aber auch
bis zum Maximum, weil sonst vergibst du dir halt die Chance,
diese Inhalte zu zeigen.


[6:16] So, also Artefakte im Fließtext, die
reduzieren deine verfügbaren Seiten für den Fließtext und das
ist schlecht. Deswegen gehören die in den Anhang. Dafür ist
auch meistens extra eine Vorgabe für die Anhangseiten gegeben,
denn auch da müssen wir uns ein bisschen reduzieren und können
ja einfach 100 Seiten Anhang hinterpacken. Ja, das geht einfach
nicht. So, jetzt habe ich gesagt, alle Artefakte in den Anhang.
Jetzt gibt es eine Sache, die du abwägen musst, und zwar die
Lesbarkeit. Du musst dir ja vorstellen, deine Dokumentation
wird von Menschen wie mir gelesen, korrigiert. Und die wollen
natürlich auch verstehen können. Und wenn du jetzt sehr
erklärungsintensive Artefakte in deiner Dokumentation hast, ich
nehme mal ein Beispiel, weiß ich nicht, eine halbe Seite
Quelltext mit super fancy Algorithmen, wo man wirklich jede
zweite Zeile erklären muss, weil man die sonst nicht versteht.
Oder du hast ein super kompliziertes Netzwerk-Therakum
gezeichnet mit drei Firewalls, mit irgendwelchen
Port-Forwardings und weiß der Geier was und du musst da ganz,
ganz viel zu erklären. Dann kann es sinnvoll sein, das Artefakt
direkt in den Text zu platzieren, weil dann kann ich auf einer
Seite, die ich gerade offen habe oder mir sogar ausgedruckt
habe, auch das gibt es noch bei Prüfenden im Jahr 2026,
überhaupt keine Frage, weil korrigieren mit Rotstift kann man
hervorragend auf Papier übrigens. Das hat sich nicht viel
geändert in den letzten Jahrzehnten.


[7:30] Deswegen, wenn ich das alles auf einer
Seite habe, kann ich das wunderbar auf einen Blick sehen, kann
das verstehen, kann zwischen Text und Abbildung hin und her
springen und kann das super nachvollziehen. Toll. Habe ich
allerdings meinen Erklärungstext auf Seite 5 und mein Artefakt
im Anhang auf Seite 27, dann muss ich halt immer hin und her
blättern, was gar nicht mal so schlimm ist, das kriegt man
schon mal hin, aber wenn Menschen wie ich, die das auf dem iPad
zum Beispiel lesen, das dann vergleichen wollen, dann wird es
schwierig, weil dann muss ich immer hin und her jumpen im
Inhaltsverzeichnis und das dauert jedes Mal ein paar Sekunden,
bis ich die Seite gefunden habe und so weiter und das ist
einfach nervig. Das heißt, es ist nicht förderlich fürs
Verständnis, wenn die Sachen so weit auseinander liegen.


[8:06] Jetzt ist es so, wenn du wirklich sehr
erklärungsbedürftige Artefakte hast, kannst du die vielleicht
in den Text packen. Da würde ich trotzdem meine zweite
Daumenregel ziehen und sagen, wenn das Ding länger ist als eine
halbe Seite, packe es trotzdem in den Anhang. warum?
Angenommen, das Klassenlehrgramm von eben wäre eine ganze Seite
groß, dann passt das ja eh nicht mehr auf die Seite, wo der
Erklärtext steht. Also müsstest du sowieso beim Lesen scrollen.
Auf Seite 14 ist die Erklärung, auf Seite 15 das
Klassenlehrgramm. Ja, super, da muss ich ja trotzdem immer hin
und her blättern, beziehungsweise hoch und runter scrollen. Da
habe ich ja nichts gewonnen. Das heißt, größere Artefakte auf
jeden Fall immer in den Anhang und kleinere und welche, die
vielleicht auch wirklich nur sinnvoll sind in Verbindung mit
dem Text, keine Ahnung. Deine Kostenberechnung, wo am Ende dann
steht, das Projekt hat 2395 Euro gekostet und direkt darüber
wäre es dann schön, vielleicht die Formel zu sehen, wie du es
berechnet hast, damit ich nicht 20 Seiten hin und her springen
muss, um diese winzige Kleinigkeit daraus zu ziehen. Also es
gibt so ein paar Sachen, wie zum Beispiel die grobe
Zeiteinplanung deiner 40 oder 80 Stunden oder eben deine
Amortisationsrechnung, deine Kostenberechnung. Solche Dinge,
die kann man auch im Fließtext platzieren. Die sind aber
meistens auch nicht sehr lang. Die sind vielleicht eine
Viertelseite, vielleicht maximal eine halbe Seite lang. Und wie
gesagt, dann greift dann halt meine Regel, dass du das auch
nach oben in den Fließtext packen kannst. Aber ansonsten würde
ich sagen, alles in den Anhang. Also Lesbarkeit ist aus meiner
Sicht der einzige Grund, warum man das in den Fließtext packen
sollte.


[9:29] So, und jetzt nochmal gesagt, wenn du diese
Fleece-Seiten quasi damit aufblähen möchtest, dass du sie mit
Artefakten zukleisterst, weil dir einfach nicht einfällt, was
du da an Fleece-Sext noch schreiben könntest.


[9:45] Dann würde ich sagen, tu das lieber nicht.
Weil, ganz ehrlich, auch wenn vielleicht der Eindruck entsteht,
die Prüfenden sind alle irgendwie alte, weiße Männer, jenseits
der 60 und wissen eigentlich gar nicht mehr so genau, was da
heute Phase ist in der IT. Ist nicht so. Die Prüfenden sind
auch nicht doof. Die sind ja nicht umsonst Prüfende geworden.
Haben also mindestens mal selber auch die Prüfung absolviert
und sind meistens langjährig irgendwo beschäftigt, in der
Ausbildung, Ausbilder oder Geschäftsführer, was auch immer.
Also das sind ja keine Vollidionen, die da sitzen. Und wenn ich
jetzt eine Doku lese, wo auf jeder zweiten Seite ein großes
Bild ist, dann werde ich dir das einfach von der Seitenzahl
abziehen. Ganz einfach. Also ich gehe am Ende, wenn ich die
Doku gelesen habe, gehe ich den Fließtext durch und ziehe mir
alle Artefakte von der Seitenzahl ab, die also mindestens
größer als eine halbe Seite sind. Wenn sie quasi sinnfrei sind
an der Stelle und nicht erklärungsbedürftig, würde ich sie auch
abziehen, wenn sie kleiner als eine halbe Seite sind. Das
heißt, ich gucke wirklich alle Fließtextseiten durch, sehe ich
ein Artefakt, ziehe ich das ab und am Ende komme ich auf
Seitenzahl 12 statt 15, auch wenn die letzte Seitenzahl 15 ist,
weil halt einfach drei Seitenartefakte dazwischen waren. Ja, so
mache ich das. Und jetzt nochmal zur Erklärung. Das heißt
nicht, dass du deswegen jetzt eine Notabzug kriegst oder auch
nur ein Prozentpünktchen Abzug bekommst, sondern für mich ist
das nur ein Indiz. Ich sehe jetzt, oh, statt 15 Seiten hat er
oder sie eigentlich nur 12 oder 13 Seiten gefüllt.


[10:59] Da kann ja dann irgendwo nur noch eine
Lücke sein, was vielleicht noch fehlt in dem Projekt. Und dann
gucke ich natürlich, welcher Inhalt fehlt denn und dafür gibt
es dann den Punktabzug. Also nicht für die reine Seitenzahl.
Ich kann es nur nochmal wiederholen. Also, denk nicht, dass die
Prüfenden Idioten sind. Die haben normalerweise schon ein paar
mehr Dokus gelesen und korrigiert und erkennen solche Tricks
natürlich auch.


[11:24] Gut, also orientier dich am eigentlichen
Problem, löst das Problem, pack sinnvollen Inhalt in die Doku
und fülle deine Seiten nicht mit Rummel auf, mit irgendeinem
Müll oder mit irgendwelchen aufgeblähten Artefakten oder damit
du auf 15 Seiten kommst. Das funktioniert nicht, weil die
Prüfenden das halt dann wieder abziehen, so wie ich zum
Beispiel. So.


[11:44] Und dann nochmal vielleicht, weil ich das
auch sehr oft sehe, Artefakte, schön und gut, sind auch sehr
wichtig, aber deine Dokumentation sollte halt nicht einfach
eine reine Ansammlung von Artefakten sein und dein Fiestext
dann ausschließlich aus sowas bestehen wie, ja, ich habe ja
auch noch ein UML-Diagramm gezeichnet, siehe Anhang. Ja, und
dann kommt das UML-Diagramm im Anhang, das ist super, aber
Vleecex gibt es dazu dann gar nicht, sondern da steht einfach
nur Überschrift Softwarearchitektur und da steht da ein Satz,
ich habe auch eine Architekturskizze gemacht, siehe Anhang 5.


[12:11] So, so füllt man den Vleecex nicht, denn
Artefakte haben keinen Selbstzweck oder stehen einfach nur so
da, sondern du machst sie aus irgendeinem Grund. Du sollst dir
zeigen, dass du auch methodisch vorgegangen bist bei deiner
Projektdurchführung. Und insbesondere mal bei der
Softwareentwicklung, da fange ich halt nicht einfach an zu
programmieren, sondern mache ich mir erst mal Gedanken, was ist
denn vielleicht mit meiner Architektur? Welche Komponenten
könnte es denn geben? Wie möchte ich die abstrahieren? Erzähl
mal. Und als Fisi das Gleiche, da sage ich nicht einfach, ja,
ich installiere jetzt hier mal die Firewall, dann gucken wir
mal, sondern du musst erst mal analysieren, welcher Traffic
muss da durch, welche Ports müssen freigegeben werden, was ist
mehr Security und tralala. Das heißt, bevor du am Ende das Ding
wirklich einbaust, hast du dir hoffentlich genug Gedanken im
Vorfeld schon gemacht. Damit das am Ende auch funktioniert. Und
genauso ist es bei der Softwareentwicklung ja auch. Das heißt,
diese Artefakte, die haben einen Sinn. Ich zeichne ein
ER-Modell nicht einfach nur für die Prüfung, weil die Prüfenden
das sehen wollen, sondern weil mir das bei der Arbeit hilft.
Wenn ich anfange zu programmieren und weiß noch nicht mal,
welche Daten ich abbilden muss. So kann ich doch nicht
vorgehen. Ich brauche doch ein Zielbild, wo ich hin will. Wie
sollen meine Tabellen aussehen, meine Klassen in der
Objektorientierung? Was gibt es denn? Woran muss ich denn
denken? Welche Besonderheiten gibt es? Dafür sind die Artefakte
da. Die sollen dir helfen. Und das sollst du auch in deiner
Projektdokumentation und später in der Präsentation zeigen,
dass die dir geholfen haben und dass du die absichtlich gemacht
hast und nicht einfach nur gezeichnet hast, weil du ja auch
noch eine Prüfungsleistung abgeben musst. Das heißt, die sind
immer in einen Kontext zu setzen.


[13:29] Und im besten Fall beschreibst du diesen
Kontext im Fließtext. Das heißt, anstatt zu sagen, ich habe
hier ein Klassendiagramm, siehe Anhang, sagst du, bevor ich
angefangen habe zu programmieren, habe ich mir Gedanken
gemacht, welche Klassen ich brauche. Ich habe das Ganze in
einem Klassendiagramm modelliert. Dabei ist mir schon
aufgefallen, oh, hier gibt es aber eine Vererbungsbeziehung.
Oder hier habe ich ein Interface eingezogen, weil die
Abstraktion hier sinnvoll war. Und analog zum Netzwerkplan. Oh,
hier ist mir aufgefallen, das ist ein ganz anderes Subnet. Da
musste ich noch einen Router dazwischen setzen. Oder weiß der
Geier was. Das heißt, so etwas sieht man ja in einem Diagramm
viel offensichtlicher, als wenn man einfach anfängt und dann
merkt, oh, habe ich gar nicht daran gedacht. So wollen wir
nicht Software entwickeln, so wollen wir keine Systeme planen.
Da brauchen wir diese Artefakte.


[14:07] Wie die dir geholfen haben, wie du die
erstellt hast, was vielleicht die Besonderheiten an diesem
konkreten Artefakt sind. Das sind Dinge, die du im Fließtext
beschreiben musst, weil die kann man an dem Artefakt alleine
nicht erkennen. Ich gucke mir dein Klassendiagramm an und denke
mir, ja, das ist ein Klassendiagramm. Aber was hast du da
mitgenommen? Was sind die Besonderheiten? Wie bist du darauf
gekommen? Das ist etwas, wofür der Fließtext da ist. Das heißt,
reine Artefaktsammlung, siehe Seite 15, bitte nicht machen,
sondern vernünftige Erklärungen im Fließtext. Zumindest meine
Herleitung und vielleicht auch einen Ausblick, was du damit
dann getan hast. Klassendiagramm ist immer mein
Lieblingsbeispiel. Ich zeichne eins, um dann später in der
Implementierungsphrase mich daran zu orientieren und die
Klassen zu programmieren. Dann ergibt das auch einen Sinn. Du
hast das Klassendiagramm nicht einfach nur gemalt, sondern du
hast es auch benutzt, um darauf aufbauend etwas anderes zu
machen. Und im besten Fall ist dir das dann leichter gefallen.
Es ging schneller oder war einfach besser, als hättest du das
Diagramm nicht gezeichnet. In diese Richtung wollen wir was im
Fließtext lesen. und dann gerne natürlich das Artefakt, aber
eben halt im Anhang.


[15:05] So, das war mein Take, glaube ich, zu den
Artefakten und wo die hingehören und warum du überhaupt welche
machst. Und jetzt nochmal als Fazit für heute. Daumenregel
nochmal zum Mitnehmen. Alle Artefakte in den Anhang packen,
insbesondere wenn sie größer sind als eine halbe Seite. Dann
auf jeden Fall. Dann gibt es eigentlich keinen Grund, die in
den Fließtext zu packen. Es gibt wenige Ausnahmen, die ich ein
bisschen aufgeführt habe. Vielleicht eine Kostenberechnung,
eine Amortisationsrechnung, ein paar Formeln oder so etwas oder
eine Zeitplanung, die grobe Zeitplanung. Das kann man
vielleicht im Fließtext lassen, aber für fast alle anderen
Artefakte würde ich sagen, immer einen Anhang. Bäm.


[15:41] Wichtig wäre, dass du die dann trotzdem in
deinem Fließtext referenzierst, dass die Artefakte nicht
einfach so im Anhang stehen und dann wundert man sich auch,
Mensch, der hat ja auch ein Klassenergaben gezeichnet. Schön,
dass ich davon gar nichts gelesen habe im Fließtext. Sondern
die müssen natürlich alle referenziert und im besten Fall auch
erklärt und eingeordnet werden. Was haben sie dir gebracht?
Warum hast du das gemacht? Was hast du vielleicht aufbauen
darauf später gemacht? Das gehört dann in den Fließtext dazu.
Also Artefakte in den Anhang, Erklärungen, Einordnungen,
Besonderheiten in den Fließtext. Und so kannst du auch locker,
locker, locker deine Vorgaben füllen, was den Fließtext angeht
und was den Anhang angeht. Also Seiten, leere Seiten,
beziehungsweise Seiten, die du nicht ausgenutzt hast, müssen
meiner Meinung nach nicht sein. Du kannst genug Inhalte
produzieren, die dann aber auch wirklich einen Mehrwert für den
Prüfenden bieten und dir dann hoffentlich auch eine gute
Abschlussnote bestellen. Darum geht es ja am Ende.


[16:29] Also das war es zum Thema Artefakte in der
Projektdokumentation. Ich hoffe, es hat dir ein bisschen
geholfen. Ich wünsche dir auf jeden Fall viel Erfolg für deine
Projektdokumentation und bis zum nächsten Mal.