Umsetzung beschreiben: Technische Dokumentation
Das Kapitel Realisierung oder Umsetzung ist meist das umfangreichste der ganzen Projektdoku – und gleichzeitig das, das am häufigsten misslingt. Viele Azubis schreiben hier eine Klick-für-Klick-Anleitung, die kein Mensch lesen will: „Dann klickte ich auf Datei → Neu → Konfiguration → OK." Das ist keine technische Dokumentation eines Projekts, sondern ein Handbuch. Was die IHK-Prüfer:innen wollen: eine nachvollziehbare Beschreibung der technischen Lösung, der wichtigen Entscheidungen, der kritischen Konfigurationen, der aufgetretenen Probleme und ihrer Lösungen. Wer das schafft, hebt sich klar von der Masse ab. Diese Lektion zeigt dir den typischen Aufbau des Realisierungs-Kapitels (chronologisch oder thematisch), was rein gehört und was nicht, wie du Konfigurations-Auszüge sinnvoll einbettest, wie du mit Quellcode umgehst, wie du Screenshots richtig einsetzt – und welche typischen Antipatterns Punkte kosten.
1) Chronologisch oder thematisch?
Du hast zwei Grund-Strukturen, je nachdem was zum Projekt passt:
| Struktur | Eignet sich für | Vorteil | Nachteil |
|---|---|---|---|
| Chronologisch (Tag 1, Tag 2 …) | Projekte mit klarer Abfolge: Migration, Schritt-für-Schritt-Aufbau | Spiegelt zeitlichen Ablauf, leicht zu schreiben | Vermischt Themen, schwer wieder zu finden |
| Thematisch (Bereiche / Komponenten) | Mehr-Komponenten-Projekte: Netz + Server + Software, oder verschiedene Module einer Anwendung | Übersichtlich, fokussiert | Erfordert Disziplin beim Schreiben |
In der Praxis dominiert thematisch. Eine Kombination ist oft sinnvoll: thematische Hauptkapitel, innerhalb jedes Kapitels chronologisch.
2) Typischer Aufbau (thematisch)
Für ein Backup-Projekt z. B.:
3) Was rein gehört – was raus
✅ Gehört rein
- Architektur-Übersicht der gebauten Lösung (Skizze)
- Begründete Konfigurations-Entscheidungen („Warum diese Einstellung?")
- Sicherheits-relevante Konfigurationen (Verschlüsselung, Auth, Firewall)
- Kritische Konfig-Auszüge mit Erläuterung – nicht ganzes File
- Aufgetretene Probleme und wie du sie gelöst hast
- Eingesetzte Hilfsmittel (Tools, Skripte, IaC)
- Test-relevante Funktionen – mit Verweis auf Test-Kapitel
- Sinnvolle Screenshots (Architektur-Diagramm, fertiges Dashboard)
- Querverweise zum Anhang für Details
❌ Gehört NICHT rein
- Klick-Anleitungen Schritt für Schritt
- Komplette Konfigurations-Dateien (gehört in den Anhang)
- Tutorial-Stil („Im nächsten Schritt klicken Sie …")
- Schwätz-Sätze („Es war eine Herausforderung, aber wir schafften es")
- Allgemeinwissen („VLAN ist eine virtuelle Netzwerk-Schicht …")
- Triviale Screenshots (Login-Dialog, Standard-Boot-Screen)
- Vollständiger Code (gehört in den Anhang, kurze Auszüge im Text)
- Werbe-Sprache des Herstellers
- Aktivitäten, die nichts mit dem Projekt zu tun haben
4) Beispiel schwach vs. stark
❌ Schwacher Absatz
„Dann startete ich den Server und ging in die Veeam-Console. Dort klickte ich auf Backup Job → New. Dann gab ich einen Namen ein und klickte auf Next. Dann wählte ich die Server, dann klickte ich wieder auf Next. Dann konfigurierte ich den Speicherort, dann klickte ich auf Next. Schließlich klickte ich auf Apply, dann auf Finish. Der Job war jetzt eingerichtet."
✅ Starker Absatz
„Für die Backup-Jobs wurde eine 3-Tier-Strategie umgesetzt: tägliche inkrementelle Sicherungen, wöchentliche Vollsicherungen, monatliche Archiv-Sicherungen mit längerer Aufbewahrung. Die Aufbewahrungs-Zeiten wurden gemäß der mit dem Auftraggeber abgestimmten Anforderung (30 Tage Tageskopien, 12 Wochen Wochenkopien, 7 Jahre Jahreskopien – steuerrechtlich begründet) konfiguriert. Die kritischen Konfigurations-Parameter zeigt Tabelle 5.1; die vollständige Job-Definition liegt als Anhang A2 bei. Verschlüsselung wurde mit AES-256 auf Repository-Ebene aktiviert, um Vertraulichkeit bei einem möglichen Diebstahl der Backup-Hardware zu gewährleisten."
5) Konfigurations-Auszüge richtig einbetten
Konfig-Auszüge gehören in den Fließtext, wenn sie Entscheidungen verdeutlichen – aber kurz. Lange Files in den Anhang:
# Auszug aus /etc/backup.conf
repository:
path: /backup/repo-01
encryption: aes-256
retention:
daily: 30
weekly: 12
yearly: 7 # steuerrechtlich begründet
Im Fließtext erklärst du den Auszug knapp: „Die yearly-Retention wurde auf 7 Jahre gesetzt, da die archivierten Sicherungen nach § 147 AO als steuerrechtliche Unterlagen 6+1 Jahre aufzubewahren sind." Das zeigt: du hast eine bewusste Entscheidung getroffen und kennst die rechtliche Grundlage.
6) Quellcode im Bericht
Bei FIAE / FIDP / FIDV ist Quellcode integraler Bestandteil. Regeln:
- Im Fließtext: nur kurze, illustrative Auszüge (5-20 Zeilen). Mit Kontext erklärt.
- Im Anhang: der relevante Code in Modulen, mit Kommentaren.
- Niemals ganzen Code dumpen – auch nicht im Anhang. Nur das, was zum Verständnis nötig ist.
- Syntax-Hervorhebung falls möglich (Word kann das).
- Repository-Link erwähnen, falls intern verfügbar.
- Sicherheit: keine echten Passwörter, Tokens, API-Schlüssel – auch im Test pseudonymisieren / mit Platzhaltern.
7) Screenshots klug einsetzen
- Sinnvolle Inhalte: Architektur-Diagramme, fertige Dashboards, Konfigurations-Übersichten, Test-Ergebnisse.
- Nicht: Login-Bildschirme, Standard-Installer-Schritte, „leere" UIs.
- Qualität: hohe Auflösung, ggf. wichtige Bereiche hervorheben (Rahmen, Pfeile).
- Bildunterschrift: immer als „Abb. X: Bezeichnung". Im Fließtext darauf verweisen.
- Datenschutz: Mitarbeiter-Namen, IPs, Hostnames, E-Mail-Adressen anonymisieren. Verzichten auf Real-Daten.
- Bezug zum Text: jedes Bild im Fließtext nennen („vgl. Abb. 5"), nicht als Selbstzweck einfügen.
- Anzahl: 8-15 Abbildungen sind typischer Bereich. Mehr ist meist zu viel.
8) Probleme dokumentieren – als Stärke!
Probleme, die du während der Realisierung gelöst hast, sind Gold wert für die Bewertung. Sie zeigen Problemlöse-Kompetenz. Struktur:
- Problem-Beschreibung: Was trat auf? Wann? Welche Symptome?
- Analyse: Was war die Ursache? Wie hast du das herausgefunden?
- Lösung: Was hast du gemacht?
- Bewertung: Funktioniert die Lösung dauerhaft? Folge-Aktionen nötig?
Beispiel:
✅ Problem-Beschreibung im Bericht
„Während des ersten Vollsicherungs-Laufs brach der Job nach ca. 40 % mit der Fehlermeldung VSS error 0x80042308 ab. Eine Analyse ergab, dass auf einem der Quell-Server eine veraltete VSS-Komponente vorlag, die mit dem Backup-Agent nicht kompatibel war. Die Lösung bestand darin, den VSS-Writer-Status mit vssadmin list writers zu prüfen und betroffene Writer (im konkreten Fall: „SqlServerWriter") über einen Dienstes-Neustart zu reinitialisieren. Anschließend lief der Backup-Job vollständig durch. Als Folge-Maßnahme wurde ein vorsorgliches Monitoring der VSS-Writer-Status in das Monitoring-Konzept aufgenommen (vgl. Kap. 5.5)."
9) Sprache, Stil, Konsistenz
- Stil: sachlich, präzise. Präteritum für Tätigkeiten („Ich konfigurierte" / „Es wurde konfiguriert"). Konsistent durch die ganze Doku.
- Wir vs. Ich: meist Ich-Form oder Passiv. Konsistent durchhalten. „Wir" nur wenn es ein Team-Projekt war und du deinen Anteil deutlich abgrenzt.
- Fachbegriffe einheitlich. Einmal eingeführt, dann beibehalten. Glossar-Verweis.
- Abkürzungen bei ersten Vorkommen ausschreiben, danach abkürzen. Im Abkürzungsverzeichnis listen.
- Querverweise nutzen: „… wie in Kap. 4.2 ausgewählt …". Statt zu wiederholen.
- Werbe-Sprache vermeiden: „leistungsstarkes Tool" → einfach „Tool".
- Übersetzungen englischer Begriffe nur, wenn sinnvoll. „Repository" bleibt „Repository", nicht „Aufbewahrungs-Ort".
10) Antipatterns
- Tutorial-Stil. „Klicken Sie auf …". Klingt wie Hersteller-Doku, gibt keine Punkte.
- Wall of text. Seitenweise Fließtext ohne Struktur. Lösung: Zwischen-Überschriften, Absätze, Tabellen, Diagramme.
- Komplette Konfig-Files im Fließtext. 2 Seiten YAML, niemand liest. Lösung: kurze Auszüge, vollständig in den Anhang.
- Screenshots als Selbstzweck. Jeden Dialog abgefilmt, kein Bezug im Text. Lösung: nur Bilder mit Mehrwert.
- Allgemeinwissen erklären. Halbe Seite über „Was ist ein VLAN" – Prüfer wissen das. Lösung: nur erklären, wenn projekt-spezifisch.
- Keine Begründungen. Was wurde wo eingestellt wird genannt – aber nicht warum. Lösung: zu jeder relevanten Entscheidung kurze Begründung.
- Probleme verschweigen. Alles lief „nach Plan". Wirkt unglaubwürdig und verschenkt Punkte. Lösung: 1-2 echte Probleme dokumentieren.
- Sicherheit ausgeklammert. Bei keinem Wort. Lösung: Authentifizierung, Verschlüsselung, Hardening kurz adressieren.
- Personen-/Datenschutz-Daten. Echte Mitarbeiter-Daten in Screenshots / Logs. Anonymisieren!
- Marketing-Sprache. „Best-of-Breed-Lösung mit synergetischen Vorteilen". Nüchtern bleiben.
- Keine Abgrenzung Eigen-/Fremd-Leistung. Bei Team-Projekten unklar, was DU gemacht hast. Lösung: explizit benennen.
- Inkonsistente Begriffe. Mal „Backup", mal „Sicherung". Lösung: einmal entscheiden, durchziehen.
Zusammenfassung
Das Realisierungs-Kapitel ist das umfangreichste der Doku (~ 3-3,5 von 12 Seiten). Es zeigt die technische Umsetzung – aber als Projekt-Doku, nicht als Hersteller-Handbuch. Bevorzugt thematische Struktur (Vorbereitung → Komponenten → Sicherheit → Monitoring → Probleme), kombiniert mit chronologischem Erzählen innerhalb der Themen. Gehört rein: Architektur-Skizze, begründete Konfigurations-Entscheidungen, Sicherheits-Aspekte, kritische Konfig-Auszüge, aufgetretene Probleme & Lösungen. Gehört NICHT rein: Klick-Anleitungen, komplette Files, Allgemeinwissen, triviale Screenshots. Sprachstil: sachlich, präzise, konsistent. Probleme aktiv dokumentieren – sie zeigen Kompetenz und bringen Punkte.
Verwandte Lektionen: Aufbau Doku · Ist & Soll · Testbericht · und mehrWeitere relevante LektionenZeitplanungFazit & AnhängeHäufige FehlerBeispiel-DokuBetriebshandbuch (K65)Server-Doku (K65)