WordPress Dokumentation: Was eine gute Systemdokumentation enthält

Ein komplexes WordPress-System lässt sich nicht zuverlässig betreiben, wenn nur einzelne Personen wissen, welche Plugins welche Aufgaben erfüllen, wo Daten gespeichert werden und wie Änderungen live gehen. Das wird besonders bei Übergaben, Relaunches, Sicherheitsvorfällen oder dem Wechsel technischer Dienstleister zum Risiko. Eine WordPress Dokumentation sollte deshalb nicht die Installation Zeile für Zeile beschreiben. Sie muss die Entscheidungen und Zusammenhänge erfassen, die für Betrieb und Weiterentwicklung relevant sind. Dieser Beitrag richtet sich an Geschäftsführungen, Projekt- und Produktverantwortliche sowie technische Leitungen, die ein gewachsenes System überblicken und handhabbar halten müssen. Die zentrale Empfehlung: Dokumentieren Sie das System so, dass eine andere qualifizierte Person seine Struktur verstehen, eine Änderung sicher planen und den Wiederanlauf nachvollziehen kann.

Kurz gesagt

Eine gute WordPress Dokumentation verbindet Inventar, Architektur, Datenmodell, Rollen, Integrationen und Betriebsabläufe. Sie erklärt nicht nur, was vorhanden ist, sondern auch, wofür es zuständig ist und welche Folgen Änderungen haben können. Besonders wichtig sind nachvollziehbare Deployment- und Wiederherstellungswege sowie ein Protokoll wesentlicher Architekturentscheidungen. Halten Sie die Dokumentation versioniert und aktualisieren Sie sie, wenn sich das System ändert.

Ausgangslage

WordPress beginnt oft als Website und wächst mit den Anforderungen: zusätzliche Inhaltstypen, Schnittstellen, Benutzergruppen, Such- oder Vergleichsfunktionen und automatisierte Prozesse kommen hinzu. Mit der Zeit verteilt sich das Wissen über Quellcode, Plugin-Einstellungen, Tickets, E-Mails und einzelne Köpfe. Die Oberfläche allein zeigt nicht, wie das System tatsächlich funktioniert.

Das betrifft insbesondere Systeme, bei denen WordPress mehr als Inhalte verwaltet. WordPress als Plattform ordnet ein, wie ein CMS zum Fundament komplexerer digitaler Systeme werden kann. Je stärker Datenmodell, Geschäftsregeln und Integrationen miteinander verbunden sind, desto wichtiger wird eine Dokumentation, die diese Beziehungen sichtbar macht.

Dokumentation ist dabei keine einmalige Beschreibung zum Projektabschluss. Sie ist Teil des Betriebs. Veraltete Angaben können gefährlicher sein als fehlende Angaben, wenn sie zu falschen Annahmen über Zuständigkeiten, Abhängigkeiten oder Wiederherstellung führen. Die Dokumentation muss deshalb einen klaren Zweck haben: Entscheidungen vorbereiten, Änderungen absichern und Übergaben ermöglichen. Dazu gehört auch, Zuständigkeiten und Aktualisierungspunkte festzulegen. Der Bezug zur Übergabe ist eng: Was eine gute Übergabe enthält beschreibt, welche Informationen beim Wechsel von Verantwortung nicht verloren gehen sollten.

Entscheidungskriterien

Bevor Sie eine Dokumentationsform festlegen, entscheiden Sie, welche Fragen sie beantworten muss. Eine brauchbare Dokumentation ist nicht möglichst umfangreich, sondern ausreichend, um konkrete Aufgaben sicher auszuführen.

1. Wer muss die Dokumentation nutzen?

Unterschiedliche Rollen brauchen unterschiedliche Ansichten. Die Geschäftsführung benötigt Überblick über Zweck, Risiken, Abhängigkeiten und Zuständigkeiten. Redaktion und Projektverantwortliche müssen verstehen, welche Inhalte und Workflows betroffen sind. Technische Mitarbeitende brauchen Details zu Code, Daten, Schnittstellen, Deployment und Wiederherstellung.

Eine einzige Textsammlung kann diese Bedürfnisse abdecken, wenn sie klar gegliedert ist. Bei größeren Systemen sind verlinkte Bereiche meist besser als ein unübersichtliches Gesamtdokument. Halten Sie fest, für wen ein Abschnitt bestimmt ist und wer ihn pflegt.

2. Welche Entscheidungen hängen davon ab?

Dokumentieren Sie zuerst Zusammenhänge, die Entscheidungen beeinflussen. Dazu zählen etwa Abhängigkeiten zwischen Plugins und Funktionen, die Herkunft wichtiger Daten oder die Folgen einer Änderung am Datenmodell. Eine vollständige Aufzählung aller Einstellungen ist nur dann sinnvoll, wenn daraus ein betrieblicher oder technischer Nutzen entsteht.

3. Wie kritisch ist ein Ausfall oder Fehler?

Je stärker eine Funktion Geschäftsprozesse, Kundenzugänge oder externe Systeme betrifft, desto genauer sollten Ablauf, Zuständigkeit und Wiederherstellung beschrieben sein. Unterscheiden Sie zwischen einer redaktionellen Website und einer Plattform, in der Benutzerrollen, Datenflüsse und geschäftliche Regeln zusammenwirken.

4. Können Abläufe von einer anderen Person wiederholt werden?

Deployment und Wiederherstellung sollten nicht auf implizitem Wissen beruhen. Dokumentieren Sie Voraussetzungen, Reihenfolge, Prüfungen und Rückweg. Die Anleitung muss zu den tatsächlich verwendeten Umgebungen und Verfahren passen. Zugangsdaten gehören nicht in die Dokumentation; halten Sie stattdessen fest, wo sie sicher verwaltet werden und wer Zugriff beantragt.

5. Lässt sich die Dokumentation aktuell halten?

Ein Dokumentationsmodell, das nach jeder Änderung aufwendig manuell nachgeführt werden muss, veraltet leicht. Halten Sie fest, welche Änderungen eine Aktualisierung auslösen und wer sie vornimmt. Verlinken Sie, wo sinnvoll, auf maßgebliche Konfigurationen oder Repositories, statt Informationen doppelt abzuschreiben.

Was die WordPress Dokumentation enthalten sollte

Inventar und Systemgrenzen

Beginnen Sie mit einem Überblick über die Bestandteile des Systems. Dazu gehören WordPress selbst, aktive Themes und Plugins, individuelle Erweiterungen, relevante externe Dienste und die genutzten Umgebungen. Erfassen Sie pro Bestandteil mindestens:

• Name und Zweck
• Zuständigkeit oder verantwortliches Team
• Abhängigkeiten zu anderen Komponenten
• Status: aktiv, optional, abzulösen oder nicht mehr verwendet
• Ort der maßgeblichen Konfiguration oder des Codes

Das Inventar sollte auch die Systemgrenze erklären: Was gehört zur WordPress-Installation, was liegt außerhalb und welche Dienste tauschen Daten mit ihr aus? Eine Liste ohne Zweck und Beziehungen hilft nur begrenzt bei der Wartung.

Architekturüberblick

Zeigen Sie in einer einfachen Übersicht, wie Frontend, WordPress, Datenbank, individuelle Erweiterungen und externe Systeme zusammenspielen. Ein Diagramm ist dann nützlich, wenn es Daten- oder Kontrollflüsse sichtbar macht. Ergänzen Sie es um kurze Erläuterungen: Welche Komponente ist für welche Aufgabe zuständig? Wo wird eine Entscheidung getroffen? Wo entstehen Abhängigkeiten?

Vermeiden Sie Diagramme, die nur technische Begriffe verbinden, ohne die Richtung oder Bedeutung der Verbindung zu erklären. Dokumentieren Sie außerdem wichtige Systemgrenzen, etwa zwischen redaktioneller Pflege und automatisierter Verarbeitung. Für eine verteilte oder stark erweiterte Installation kann der Beitrag WordPress als Betriebssystem helfen, die Architekturperspektive zu schärfen.

Datenmodell und Inhalte

Beschreiben Sie, welche Inhalte und Datenobjekte es gibt und wie sie miteinander verbunden sind. Erfassen Sie dafür Inhaltstypen, Taxonomien, wichtige Felder, Beziehungen und den Zweck der jeweiligen Struktur. Nennen Sie außerdem, welche Daten redaktionell gepflegt, importiert oder von anderen Systemen bereitgestellt werden.

Entscheidend ist nicht nur, wo ein Feld gespeichert wird, sondern welche Bedeutung es im Prozess hat. Wenn ein Feld, eine Taxonomie oder ein Inhaltstyp verändert wird: Welche Ansichten, Exporte, Suchfunktionen oder Integrationen sind betroffen? Die Entscheidung zwischen Inhaltstypen, Taxonomien und eigenen Tabellen ist eng mit der Systemarchitektur verbunden; dazu mehr unter WordPress-Daten modellieren.

Rollen und Rechte

Halten Sie fest, welche Benutzergruppen es gibt, welche Aufgaben sie erfüllen und auf welche Funktionen oder Daten sie zugreifen dürfen. Dokumentieren Sie sowohl WordPress-Rollen als auch projektspezifische Berechtigungen, falls vorhanden. Beschreiben Sie, wer Rollen vergibt und wie Änderungen an Berechtigungen geprüft werden.

Vermeiden Sie dabei eine bloße Liste von Rollennamen. Die entscheidende Information ist, was eine Person mit der jeweiligen Rolle tun kann und welche Auswirkungen das auf Inhalte oder Prozesse hat. Bei Systemen mit externen Benutzergruppen sollten Sie auch erklären, ob diese im WordPress-Backend, über ein Frontend oder über eine Schnittstelle arbeiten.

Integrationen und Datenflüsse

Für jede Schnittstelle sollten Zweck, Richtung und Auslöser des Datenaustauschs nachvollziehbar sein. Halten Sie fest, welche Daten gesendet oder empfangen werden, welche Komponente dafür zuständig ist und wie Fehler erkannt oder bearbeitet werden. Beschreiben Sie Authentifizierungsverfahren auf einer konzeptionellen Ebene, aber dokumentieren Sie keine Secrets oder Zugangsdaten.

Achten Sie besonders auf Daten, die in mehreren Systemen verändert werden können. Legen Sie fest, welches System für welchen Wert maßgeblich ist und wie Konflikte behandelt werden. Wenn eine API Teil der Architektur ist, sollte die Dokumentation nicht nur einzelne Endpunkte aufzählen, sondern deren Rolle im Gesamtsystem erklären. Siehe dazu WordPress REST API richtig einsetzen.

Deployment und Betrieb

Eine Betriebsdokumentation sollte beantworten, wie eine Änderung von der Entwicklung bis in die produktive Umgebung gelangt. Beschreiben Sie verwendete Umgebungen, Freigabeschritte, notwendige Prüfungen und den vorgesehenen Rückweg, falls eine Änderung Probleme verursacht. Ergänzen Sie, welche Aufgaben regelmäßig anfallen und wer dafür zuständig ist.

Dokumentieren Sie den tatsächlichen Prozess, nicht einen idealisierten Ablauf. Wenn etwa Konfigurationen oder Datenbankänderungen gesondert behandelt werden, muss die Anleitung das berücksichtigen. Verknüpfen Sie Deployment-Schritte mit den relevanten Tests oder Freigaben. Das Prinzip Know → Change → Prove bietet dafür eine klare Abfolge: Zustand erfassen, Änderung kontrolliert ausführen und Wirkung prüfen.

Entscheidungsprotokoll

Halten Sie wesentliche Architekturentscheidungen knapp und nachvollziehbar fest. Ein Eintrag sollte enthalten:

• die Entscheidung und den Zeitpunkt
• den Anlass oder das zu lösende Problem
• betrachtete Alternativen und die maßgeblichen Kriterien
• erwartete Folgen und bekannte Nachteile
• Bedingungen, unter denen die Entscheidung erneut geprüft werden sollte

Das ist besonders wichtig bei Entscheidungen, die später nicht mehr aus dem Code allein hervorgehen: Warum wurde eine Erweiterung individuell gebaut? Warum werden Daten auf eine bestimmte Weise modelliert? Welche Abhängigkeit wurde bewusst akzeptiert? Eine Sammlung solcher Einträge verhindert, dass dieselben Fragen ohne den ursprünglichen Kontext erneut entschieden werden.

Wiederherstellung

Dokumentieren Sie, welche Bestandteile für einen Wiederanlauf erforderlich sind und in welcher Reihenfolge sie wiederhergestellt werden. Dazu gehören – abhängig von der Architektur – Datenbank, Dateien, Konfiguration und externe Abhängigkeiten. Halten Sie fest, wer den Wiederherstellungsprozess anstoßen darf, welche Voraussetzungen nötig sind und wie geprüft wird, ob das System danach funktioniert.

Ein vorhandenes Backup beweist noch nicht, dass sich das System damit vollständig wiederherstellen lässt. Beschreiben Sie deshalb auch, wann und wie die Wiederherstellung getestet wird und welche Ergebnisse festgehalten werden. Prüfen Sie, ob wiederhergestellte Daten und Konfigurationen zusammenpassen. Weitere Einordnung bietet Warum Backups allein kein Betriebssicherheitskonzept sind.

Praxisbeispiel

Bei Wendewerk verbindet eine WordPress-Plattform Krankenkassen- und Leistungsdaten mit mehreren Benutzergruppen und Anwendungen. Zum System gehören rund 17 eigene Plugins auf einer gemeinsamen Plattform, ein Datenmodell in ACF-Feldern, Rollen für Krankenkassen, Experten, Präventionsanbieter und Versicherte sowie Besucher-Tools wie Vergleich und Beitragsrechner. Eine Token-authentifizierte REST-API stellt eine Verbindung zu einer App her. Für die KI-gestützte Extraktion von Satzungstexten gibt es ein Staging und einen Review vor dem Zusammenführen.

Eine Systemdokumentation für eine solche Architektur sollte diese Zusammenhänge auffindbar machen: Welche Plugins übernehmen welche Aufgaben? Wie hängen Rollen und Daten zusammen? Welche Informationen fließen über die API? An welcher Stelle wird ein KI-Ergebnis geprüft, bevor es in den weiteren Prozess gelangt? Das Beispiel zeigt, warum ein Plugin-Inventar allein nicht genügt. Wendewerk im Überblick.

Typische Fehler

• Nur Plugins auflisten: Ohne Zweck, Zuständigkeit und Abhängigkeiten bleibt unklar, was eine Änderung beeinflussen kann.
• Dokumentation mit einer Übergabe verwechseln: Eine einmalige Übergabe ersetzt keine laufende Pflege. Verantwortlichkeiten und Aktualisierungsanlässe müssen feststehen.
• Jede Einstellung beschreiben: Detailfülle ohne Entscheidungsnutzen macht wichtige Informationen schwer auffindbar.
• Datenflüsse auslassen: Schnittstellen wirken oft über Systemgrenzen hinweg. Ohne Richtung und Datenverantwortung bleiben Fehler schwer einzugrenzen.
• Geplante Abläufe statt realer Abläufe dokumentieren: Stimmen Anleitung und Betrieb nicht überein, sinkt das Vertrauen in die Dokumentation.
• Wiederherstellung ungeprüft lassen: Ein dokumentiertes Verfahren ist erst belastbar, wenn es unter passenden Bedingungen nachvollzogen und geprüft wurde.
• Entscheidungen nicht begründen: Ohne Anlass und Kriterien ist später kaum erkennbar, ob eine frühere Lösung noch passt.

Empfehlung

Wenn WordPress vor allem eine überschaubare Website mit wenigen Erweiterungen betreibt, genügt meist eine knappe, gepflegte Übersicht zu Komponenten, Zuständigkeiten, Deployment und Wiederherstellung.

Wenn mehrere Inhaltstypen, Rollen oder externe Dienste zusammenspielen, ergänzen Sie die Übersicht um Architekturdiagramm, Datenmodell und Schnittstellenbeschreibung.

Wenn WordPress Geschäftsprozesse, Kundenbereiche oder Anwendungen unterstützt, dokumentieren Sie zusätzlich Berechtigungen, Datenverantwortung, Freigabeschritte, Fehlerwege und Entscheidungsprotokoll.

Wenn ein System gewachsen ist und Wissen auf mehrere Personen verteilt liegt, beginnen Sie nicht mit einer vollständigen Beschreibung jeder technischen Einzelheit. Erfassen Sie zuerst die kritischen Abhängigkeiten und Abläufe, die für Änderungen, Betrieb und Wiederherstellung gebraucht werden. Danach erweitern Sie die Dokumentation anhand konkreter Entscheidungen und Übergaben.

Checkliste

• Sind Zweck, Systemgrenzen und verantwortliche Personen benannt?
• Gibt es ein aktuelles Inventar mit Zweck und Abhängigkeiten der Komponenten?
• Zeigt ein verständlicher Überblick die wichtigsten Architektur- und Datenflüsse?
• Sind Inhaltstypen, Felder, Beziehungen und Datenherkunft beschrieben?
• Ist nachvollziehbar, welche Rollen welche Aufgaben und Rechte haben?
• Sind Integrationen mit Richtung, Zweck und Fehlerbehandlung dokumentiert?
• Können Deployment und Rückweg anhand der Anleitung nachvollzogen werden?
• Sind wesentliche Architekturentscheidungen mit Anlass und Kriterien festgehalten?
• Ist beschrieben, wie eine Wiederherstellung geprüft wird?
• Ist klar, wer die Dokumentation bei welchen Änderungen aktualisiert?

Häufige Fragen

Wie detailliert sollte eine WordPress Dokumentation sein?

So detailliert, dass die zuständigen Personen Betrieb, Änderungen und Wiederherstellung nachvollziehen können. Der Umfang richtet sich nach Abhängigkeiten und möglichen Folgen eines Fehlers, nicht nach der Zahl der Dokumentseiten.

Wo sollte die Dokumentation liegen?

Dort, wo die zuständigen Personen sie finden und pflegen können. Technische Informationen sollten möglichst versioniert und mit den maßgeblichen Repositories oder Betriebshinweisen verknüpft sein. Zugangsdaten gehören in dafür vorgesehene sichere Systeme, nicht in die Dokumentation.

Wie bleibt die Dokumentation aktuell?

Definieren Sie konkrete Aktualisierungsanlässe, etwa Änderungen an Datenmodell, Rollen, Integrationen oder Deployment. Machen Sie die Pflege zu einem Teil des Änderungsprozesses und benennen Sie eine verantwortliche Rolle.

Muss jede WordPress-Installation eine Architekturzeichnung haben?

Nicht zwingend. Eine einfache Website kann mit einer klaren Komponentenübersicht auskommen. Sobald Datenflüsse, externe Dienste oder individuelle Geschäftslogik zusammenspielen, hilft eine Zeichnung, Abhängigkeiten schneller zu erkennen.

Weiterführend

• WordPress als Plattform: Architektur für komplexe Websites und digitale Systeme
• WordPress-Daten modellieren
• Know → Change → Prove: WordPress-Änderungen sicher durchführen
• Field Note: Was eine gute Übergabe enthält