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.
Kommentare (0)
Melde dich an, um einen Kommentar zu schreiben.