Qualitätssicherungsmaßnahmen, Dokumentationstypen
Dieser Beitrag ist eine Begriffserklärung zu Dokumentation als QS‑Werkzeug – inklusive Prüfungsfragen und Tags.
In a Nutshell
Dokumentation macht Anforderungen, Verhalten und Nachweise prüfbar. Kernartefakte: Benutzerdokumentation, Schnittstellendokumentation, Programmdokumentation, Netzwerkdokumentation, Testprotokolle und Checklisten – alle mit klaren Zielen, Struktur, Verantwortlichen und Pflegeprozess.
Kompakte Fachbeschreibung
Benutzerdokumentation
Adressiert Anwender/Betrieb: Aufgaben, Schrittfolgen, Fehlerszenarien, Supportwege. Ziel: Selbsthilfe, weniger Support.
Schnittstellendokumentation
Definiert Verträge: Endpunkte, Datenschemata, Fehlercodes, Auth, Versionierung. Grundlage für Interoperabilität und Contract Tests.
Programmdokumentation
Fokussiert auf wartbare Implementierung: Architekturübersicht, Module, öffentliche Schnittstellen, Invarianten, Code‑Kommentare, Build‑/Runbook.
Netzwerkdokumentation
Beschreibt Topologie, Zonen, Ports, Protokolle, Flows, Sicherheitskontrollen. Grundlage für Härtung und Fehleranalyse.
Testprotokolle
Belegen Testwirksamkeit: Testplan‑Bezug, Umgebung, Fälle, Ergebnisse, Defekte, Freigaben.
Checklisten
Standardisieren wiederkehrende Prüfungen (PR Reviews, Go‑Live, Onboarding). Reduzieren Auslassungen.
Für die AP2 zählt die prüfbare Verbindung: Anforderung → Nachweis → Ergebnis, verlinkt über Tickets, Commits, Builds, Releases.
Prüfungsrelevante Stichpunkte
- Zielgruppe + Zweck je Dokument klar
- Versionierung, Änderungsverfolgung, Verantwortliche, Review‑Zyklus
- Mindestinhalte je Typ (Strukturvorlagen nutzen)
- Nachweisfunktion (Abnahme, Audit, Support, Betrieb)
- Qualität: aktuell, vollständig, eindeutig, testbar, verständlich
- Verknüpfung mit QS (Anforderung ↔ Testfall ↔ Ergebnis ↔ Defekt ↔ Release)
- Werkzeuge: Wikis, Markdown‑Repos, Diagramme als Code, Ticket‑Verknüpfungen
- IHK‑Relevanz: gezeigt, dass Doku gepflegt, versioniert, verlinkt und im Prozess verankert ist
Kernkomponenten
- Benutzerdokumentation (Zielgruppe, Aufgaben, Schritte, Beispiele, Fehlerhilfe, Support)
- Schnittstellendokumentation (Zweck, Endpunkte, Methoden, Schemata, Fehler, Auth, Versionierung)
- Programmdokumentation (Architektur, Module, öffentliche Schnittstellen, Datenmodelle, Invarianten, Build/Run)
- Netzwerkdokumentation (Topologie, IP‑Bereiche, Zonen, Ports/Protokolle, Firewall‑Regeln, Flows, HA)
- Testprotokoll (Testplan‑Bezug, Umgebung, Fälle, Ist‑Ergebnisse, Defekte, Freigaben)
- Checkliste (Zweck, Prüfpunkte, Evidenzen, Verantwortliche, Datum, Ergebnis, Abweichungen)
- Governance (Owner, Review‑Zyklus, Änderungslog, Freigabestufen)
- Ablage (zentrale Quelle, Zugriffsrechte, Suchbarkeit, Versionierung im Repo)
- Qualität (Leseprüfung, Konsistenzprüfung, Aktualitätstracking, Link‑Prüfung)
- Compliance (Bezug zu ISO 25010, Datenschutz, Sicherheit, Betrieb)
Praxisbeispiel (Warenkorb‑API + Admin‑Portal)
Benutzerdokumentation:
- Zielgruppe: Sachbearbeitung, Admin
- Aufgaben: Bestellung erfassen, Gutschrift erstellen
- Schrittfolge: Start → Login → Kunde suchen → Artikel hinzufügen → Rabatt prüfen → Bestellung abschließen
- Fehlerhilfe: häufige Fehlermeldungen mit Lösung
- Support: Kontaktzeiten, Ticketprozess
Schnittstellendokumentation:
- OpenAPI: POST /api/orders, GET /api/orders/{id}
- Schemata: Order, Position (Constraints)
- Fehler: 400 Validierung, 401 Auth, 409 Konflikt
- Auth: OAuth2, Scopes order:write, order:read
- Versionierung: Accept: application/vnd.shop.v1+json + Deprecation Plan
Programmdokumentation:
- Architektur: Layering, Controller → Service → Repository, Ports & Adapter
- Wichtige Klassen: OrderService, Invariante: Gesamtsumme ≥ 0
- Konfiguration: Profile, Secrets via Vault
- Build: Tooling, Startbefehle, Logging, Tracing
Netzwerkdokumentation:
- Zonen: Internet → DMZ → App → DB
- Flows: Browser → Portal (TLS 443) → API (TLS 443) → DB (5432)
- Firewall: prinzipielle Freigaben, Monitoring‑Punkte
- HA: Reverse Proxy, 2 Instanzen, DB‑Replikat
Testprotokoll:
- Testplan‑Referenz: TP‑007, Umgebung: Staging‑23
- Fälle: Bestellung mit Rabatt, Grenzwerte, Fehlerpfade
- Ergebnis: bestanden, bestanden, fehlgeschlagen → Defekt ID 532
- Freigabe: Product Owner bestätigt, Datum, Signatur
Checklisten:
- PR‑Review: Architektur, Sicherheit, Tests, Doku aktualisiert
- Go‑Live: Monitoring aktiv, Runbooks vollständig, Rollback vorhanden, Feature Flags vorbereitet
Vorteile und Nachteile
Vorteile
- Nachvollziehbarkeit, Abnahmefähigkeit
- Schnellere Einarbeitung
- Geringere Betriebs‑/Supportkosten
- Auditfähigkeit
Nachteile
- Pflegeaufwand
- Risiko veralteter Inhalte
- Disziplin & Ownership erforderlich
Typische Prüfungsfragen (mit Kurzantwort)
- Zweck der Schnittstellendokumentation in der QS? Definiert prüfbare Verträge, ermöglicht Contract Tests, verhindert Integrationsfehler.
- Mindestinhalte der Benutzerdokumentation? Zielgruppen, Aufgaben, Schrittfolgen, Beispiele, Fehlerhilfe, Supportwege, Versionsstand.
- Wie hilft Programmdokumentation der Wartbarkeit? Beschreibt Architektur, Module, öffentliche Schnittstellen, Invarianten → sinkt Einarbeitungs‑/Änderungsaufwand.
- Was muss ein Testprotokoll enthalten? Testplan‑Bezug, Umgebung, Testfälle, Ist‑Ergebnisse, Defekte, Freigaben, Datum, Verantwortliche.
- Wann sind Checklisten sinnvoll? Bei wiederkehrenden Tätigkeiten mit Risiko (PR Reviews, Go‑Live, Onboarding).
Wichtigste Quellen
- https://iso25000.com
- https://www.w3.org/TR/using-aria (für semantische UI‑Dokumentation)
- https://plantuml.com