Wohin Dokumentation gehört

Was zu einem bestimmten Commit, Branch oder Release passen muss, gehört ins Repository des Pakets; was Fragen aus Nutzung und Administration beantwortet, gehört ins Wiki.

Geltung

In Kraft seit: 26. September 2026
Beschlossen von: The White Knight Labs als Betreiber dieses Wikis
Gilt für:
- die eigenen DokuWiki-Pakete des Projekts DokuWiki-Plugins (29 Pakete, deren Namen mit wk beginnen)
- deren Repositorys
- deren Wiki-Seiten unter <lang>:wiki:dwe:<package>
- die Seiten für Mitwirkende unter <lang>:wiki:help:projects
Vorrang: Diese Seite ist die maßgebliche Fassung der Regel. Kurzfassungen an anderer Stelle – der hauseigene Dokumentations-Skill und die CONTRIBUTING-Dateien – verweisen hierher. Weichen sie ab, gilt diese Seite.

Zweck

Jede Information steht an genau einer Stelle, damit ihr keine zweite Fassung widersprechen kann.

Bevor die Regel galt, zeigte eine Bestandsaufnahme, was doppelte Pflege bewirkt. Die 29 Pakete führten ihre Benutzerdokumentation zweimal: als englische Markdown-Dateien im Repository und als Wiki-Seiten in bis zu fünf Sprachen. Insgesamt behandelten 145 Dokumentpaare dasselbe Thema; bei fast allen deckten sich die beiden Texte nur teilweise. Dazu wichen 202 Aussagen vom Code ab. Drei Beispiele:

Die Referenz eines Menü-Plugins nannte nur 2 seiner 5 Einstellungen.
Eine README-Datei beschrieb eine Syntax, die das Plugin nicht erkennt.
Standardwerte im Wiki widersprachen dem Code.

Aus einer kopierten README-Datei wurden innerhalb von zehn Wochen drei verschiedene Texte: die Kopie im Wiki, die Fassung im Repository und die ausgelieferte Datei.

Für wen

Die Regel richtet sich an alle, die Wiki-Seiten schreiben, zu den Paketen beitragen, Pakete als Maintainer betreuen oder Änderungen prüfen.

Grundsätze

Prüffrage: Muss diese Information zu einem bestimmten Commit, Branch oder Release passen? Wenn ja, gehört sie ins Repository des Pakets. Lautet die Antwort nein und beantwortet die Information eine Frage aus Nutzung oder Administration, gehört sie ins öffentliche Wiki.
Die Referenz liegt beim Code. Öffentliche Schnittstelle, Syntax, Konfigurationsschlüssel (mit Typ und Standardwert) und Verträge stehen im Repository, in docs/api-reference.md auf Englisch. Die Wiki-Seite reference eines Pakets ist ein Wegweiser: Sie nennt, was die Referenz enthält, und verweist auf den Repository-Bildschirm des Projekts. Dort lässt sich die Datei für jeden Branch und jeden Commit lesen. Das Wiki kopiert die Referenz nicht und bettet sie nicht ein.
Verweisen statt kopieren. Zwischen Repository und Wiki wird nie kopiert. Stattdessen wird verwiesen, oder die zweite Stelle wird aus der ersten erzeugt. Eine Kopie, die jemand von Hand abgleichen muss, weicht mit der Zeit vom Original ab – das belegt die Bestandsaufnahme unter Zweck.
„Dokumentation zuerst“ ist eine Arbeitsweise, keine Rangordnung. Eine Spezifikation darf vor dem Code entstehen. Ab der Veröffentlichung ist der Code maßgeblich: Der Text wird an das angepasst, was der Code tut, und der Vermerk „Spezifikation“ entfällt.
Jeder Ort hat seine Sprache. Markdown-Dateien im Repository sind ausschließlich auf Englisch verfasst. Wiki-Seiten gibt es auf Deutsch, Englisch und Slowenisch; jede Fassung entsteht in ihrer eigenen Sprache aus den gesicherten Fakten und wird von der Redaktion dieser Sprache geprüft. Aus einer anderen Fassung wird nie übersetzt. Arbeitselemente sowie die Texte von Commits und Pull-Requests dürfen auf Deutsch verfasst sein. Namen von Dateien und Namensräumen sind immer englisch, unabhängig von der Sprache des Inhalts.
Die Dokumentation folgt den Berechtigungen des Projekts. Jede Dokumentation ist genauso sichtbar wie das Projekt, zu dem sie gehört. Das Projekt DokuWiki-Plugins ist öffentlich; die README-Dateien seiner Pakete und die Dateien unter docs/ sind deshalb ebenfalls öffentlich.

Regeln im Einzelnen

Ort nach Inhalt

Inhalt	Ort
Überblick, Schnellstart, Tutorial, Anleitungen und Fehlerdiagnose für Nutzung und Administration; Installation und Aktualisierung; Produktkonzepte	Wiki: `<lang>:wiki:dwe:<package>:*`
öffentliche Schnittstelle, Syntax und Parameter der Marken, Konfigurationsschlüssel mit Typ und Standardwert, Verträge	Repository: `docs/api-reference.md` und `docs/contract-*.md` (Englisch); im Wiki die Seite `<lang>:wiki:dwe:<package>:reference` als Wegweiser
Voraussetzungen und Abhängigkeiten	Repository: `wkcomponent.json`; die Komponentenmatrix im Wiki wird daraus erzeugt
Versionsgeschichte	Repository: `CHANGELOG.md`, sofern ein Paket eine solche Datei führt, sonst der Commit-Verlauf; nie eine Wiki-Seite
Entscheidungen; Notizen ohne Entscheidung	Repository: `docs/adr/NNNN-<slug>.md`; `docs/notes/<slug>.md`
interne Architektur, Übersicht der Klassen und Dateien, Interna der Datenhaltung	Repository: `docs/architecture.md`
Bauen, Entwicklungsumgebung und Tests eines einzelnen Pakets	Repository: `docs/development.md` und `CONTRIBUTING`
Bedrohungsmodell	Repository: `docs/threat-model.md`
`README`	Repository, als Wegweiser: was das Paket ist, Verweise auf seine Wiki-Seiten, Voraussetzungen, Aufbau des Repositorys, Entwicklung, Änderungsprotokoll, Lizenz
projektübergreifender Weg zum Mitwirken: Zugang, Klonen, Änderung einreichen, aktueller Stand der Regeln	Wiki: `<lang>:wiki:help:projects:*`

Ort nach Schicht

Die Schichten L1 bis L6 stammen aus dem Schichtenmodell der hauseigenen Dokumentationsrichtlinie.

Schicht	Ort
L1 Überblick und Einstiegsseite	Wiki
L2 Tutorial und Anleitung	Wiki
L3 Fehlerdiagnose (die Überschriften nennen Symptome)	Wiki
L4 Konzepte	Wiki für Produktkonzepte; Repository (`docs/architecture.md`) für Interna
L5 Referenz (öffentliche Schnittstelle, Konfiguration)	Repository; das Wiki verweist darauf
L5 interne Referenz	Repository
L6 technische Notizen, Entscheidungen, Änderungsprotokoll	Repository

Verweise zwischen Repository und Wiki

Richtung	Vorgehen
vom Wiki ins Repository	Verweis auf den Repository-Bildschirm des Projekts. Als Kontext dient die Startseite des Pakets in der Sprache der Leserschaft; dadurch bleibt die Oberfläche in dieser Sprache. Form: `[[<lang>:wiki:dwe:<package>:start?do=wkdoadogit_repo&ns=code:dokuwiki-plugins:<package>&file=/docs/api-reference.md\|…]]`. Der Bildschirm zeigt zunächst den Standardbranch `main`; andere Branches und einzelne Commits lassen sich dort auswählen. Zum Lesen ist kein Konto nötig, zum Klonen und für den ZIP-Download eine Anmeldung.
vom Repository ins Wiki	absoluter Verweis auf die englische Seite, etwa `https://www.wvds.it/wiki/doku.php?id=en:wiki:dwe:<package>:start`. Die Sprachwahl der Seite führt zu den vier anderen Sprachen.
nicht zulässig	Kopien von Repository-Dateien als Medien im Wiki; Repository-Dateien, die aus Wiki-Seiten erzeugt werden; eingebettete Repository-Dateien auf Paketseiten

Sprache nach Ort

Ort	Sprache
Repository: `README`, `docs/**`, `CHANGELOG`, `CONTRIBUTING`, Kommentare im Code	ausschließlich Englisch
Wiki-Seiten	Deutsch, Englisch und Slowenisch; jede Fassung in ihrer Sprache aus den gesicherten Fakten geschrieben und von der Redaktion dieser Sprache abgenommen; Oberflächentexte wörtlich so zitiert, wie die Oberfläche sie in dieser Sprache zeigt
Arbeitselemente, Commit-Nachrichten, Beschreibungen von Pull-Requests	Deutsch zulässig
Datei- und Verzeichnisnamen, Namensräume, Seitenkennungen, Namen von Mediendateien	immer Englisch; die Seitenkennungen der Sprachfassungen unterscheiden sich nur im ersten Segment

Sprachressourcen

Hausleitfaden: Redaktionsleitfaden – The White Knight Labs
Normative Grundlage: Duden und DIN 5008