Dokumentationspflege

Dokumentationspflege

Führende Quelle

Für technische Entwickler- und Betriebsdokumentation ist das GitHub-Wiki die führende Quelle. docs-site/ bleibt derzeit als separate, ausgelieferte MkDocs-Seite bestehen, ist aber keine automatische Kopie des Wikis.

Solange beide Systeme existieren, gilt:

• Entwickler-, Test-, API-, Datenbank- und Deployment-Inhalte werden zuerst im Wiki aktualisiert.
• Benutzeranleitungen können weiterhin in docs-site/docs/benutzer/ gepflegt werden.
• Technische MkDocs-Seiten dürfen nicht stillschweigend als aktuell vorausgesetzt werden.
• Eine Änderung, die beide Zielgruppen betrifft, aktualisiert beide Quellen im selben Arbeitsvorgang oder dokumentiert ausdrücklich die Abweichung.

Wann Dokumentation geändert werden muss

• neue oder geänderte Env-Variable;
• neuer Service, Port, Domain oder Hintergrundjob;
• API-Vertrag, Rolle oder Authentifizierungsablauf;
• Migration oder neues Datenmodell-Prinzip;
• Testbefehl, CI-Job oder Release-Gate;
• Deployment-, Backup- oder Restore-Schritt;
• behobener oder neu erkannter offener Punkt.

Wiki-Struktur

• Home.md: kurzer Einstieg
• _Sidebar.md: vollständige Navigation
• Übersichtsseiten: Links und Orientierung
• Fachseiten: konkrete, ausführbare Anweisungen

Dateinamen verwenden stabile, sprechende Wiki-Slugs. Interne Links werden ohne .md geschrieben, z. B. [Testprozess](Testprozess).

Pflegecheckliste

• Aussage gegen aktuellen Code/Skript geprüft.
• Befehle und Dateipfade existieren.
• Keine Secrets oder internen Zugangsdaten enthalten.
• Links und Überschriften funktionieren.
• Sicherheitswarnungen stehen unmittelbar beim riskanten Schritt.
• Veraltete Aussage entfernt statt nur zusätzlich relativiert.
• „Bekannte offene Punkte“ wurde bei Abschluss aktualisiert.
• Startseite/Sidebar wurden bei neuen Seiten ergänzt.

Veraltete Inhalte

Zeitabhängige Aussagen wie Testanzahl, offene Audits oder konkrete Versionen benötigen ein Datum oder sollten strukturell formuliert werden. Automatisch ermittelbare Zahlen sollten nicht ohne Nutzen als dauerhafte Wahrheit dokumentiert werden.

Widerspricht das Wiki dem ausführbaren Code, wird der Code zunächst als beobachteter Ist-Zustand behandelt und der Widerspruch geklärt. Sicherheits- oder Betriebsverhalten darf nicht allein aufgrund einer alten Dokumentationsaussage geändert werden.