WordPress technische Dokumentation erstellen: Der praxisnahe Ratgeber

Eine gute technische Dokumentation macht eine WordPress-Website verständlich, wartbar und sicher. Sie hält fest, wie Hosting, WordPress-Core, Themes, Plugins, Benutzerrechte, Backups und individuelle Anpassungen zusammenspielen. Dadurch sinkt die Abhängigkeit von einzelnen Personen, Fehler lassen sich schneller eingrenzen und Übergaben werden deutlich einfacher.

In diesem Ratgeber erfahren Sie, wie Sie eine technische WordPress-Dokumentation erstellen, welche Inhalte wirklich relevant sind und wie Sie den Aufwand sinnvoll begrenzen. Der Schwerpunkt liegt auf einer klaren, dauerhaft nutzbaren Dokumentation für Teams, Agenturen, interne Verantwortliche und externe Dienstleister.

Passende WordPress Hilfe zum Thema

Warum eine technische WordPress-Dokumentation wichtig ist

Eine WordPress-Website besteht selten nur aus einer Installation und einigen Seiten. Meist wirken mehrere technische Ebenen zusammen: Domain und DNS, Hosting, Datenbank, Medienverwaltung, Erweiterungen, externe Dienste, Benutzerkonten und individuelle Code-Anpassungen. Ohne nachvollziehbare Dokumentation bleibt dieses Zusammenspiel häufig im Erfahrungswissen einzelner Beteiligter verborgen.

Das wird spätestens dann problematisch, wenn eine zuständige Person ausfällt, ein Dienstleister wechselt oder eine Störung auftritt. Eine Dokumentation beantwortet in solchen Situationen wichtige Fragen:

  • Wo wird die Website gehostet und wer besitzt Zugriff auf das Kundenkonto?
  • Welche Versionen, Themes und Plugins sind im Einsatz?
  • Welche Anpassungen wurden individuell programmiert?
  • Wie werden Backups erstellt und wie kann eine Wiederherstellung ablaufen?
  • Welche externen Dienste sind technisch oder rechtlich mit der Website verbunden?
  • Welche Änderungen dürfen nur nach einer Prüfung oder Freigabe erfolgen?

Eine gute Dokumentation ist dabei kein möglichst langer Text. Sie ist ein verlässliches Nachschlagewerk mit klaren Zuständigkeiten, aktuellen Informationen und verständlichen Anweisungen. Sensible Zugangsdaten gehören nicht ungeschützt in das Dokument. Stattdessen sollte die Dokumentation auf einen sicheren Passwortmanager oder ein getrenntes Berechtigungssystem verweisen.

Vorbereitung: Umfang und Zielgruppe festlegen

Schematische Architektur einer WordPress-Website mit Hosting, Datenbank, Theme und Plugins
Eine Architekturübersicht zeigt die wichtigsten technischen Abhängigkeiten auf einen Blick.

Die Darstellung hilft dabei, den Weg von Domain und Hosting bis zur Website-Ausgabe verständlich zu erklären. Besonders wichtig sind die Verbindungen zwischen WordPress, Datenbank, Erweiterungen und externen Diensten.

Bevor Sie mit dem Schreiben beginnen, sollten Sie festlegen, für wen die Dokumentation gedacht ist. Eine technische Übergabe an eine Agentur benötigt andere Details als eine interne Anleitung für Redakteurinnen und Redakteure. Häufig ist es sinnvoll, mehrere Ebenen zu kombinieren:

  • Überblick: Die wichtigsten Systeme, Zuständigkeiten und Abhängigkeiten auf wenigen Seiten.
  • Betrieb: Regelmäßige Aufgaben wie Updates, Backups, Prüfungen und Freigaben.
  • Entwicklung: Code-Struktur, lokale Entwicklungsumgebung, Deployment und individuelle Funktionen.
  • Redaktion: Hinweise für Inhalte, Medien, Benutzerverwaltung und wiederkehrende Abläufe.
  • Notfall: Vorgehen bei Ausfällen, Sicherheitsvorfällen oder fehlerhaften Aktualisierungen.

Definieren Sie außerdem die Grenze des Projekts. Soll nur die WordPress-Installation dokumentiert werden oder auch der Webserver, die Domainverwaltung, E-Mail-Dienste und externe Schnittstellen? Dokumentieren Sie mindestens alle Systeme, deren Ausfall oder Änderung die Website direkt beeinflussen kann.

Bestandsaufnahme statt Vermutungen

Eine belastbare Dokumentation beginnt mit einer Bestandsaufnahme. Notieren Sie nur Informationen, die Sie überprüft haben. Öffnen Sie beispielsweise die Hosting-Verwaltung, prüfen Sie die installierten Erweiterungen und vergleichen Sie die sichtbaren Funktionen der Website mit dem vorhandenen Code. Wenn eine Angabe unklar ist, kennzeichnen Sie sie als offen und vergeben Sie eine verantwortliche Person für die Klärung.

Hilfreich ist eine einfache Tabelle mit den Spalten „Thema“, „aktueller Stand“, „Quelle oder Nachweis“, „verantwortlich“ und „zuletzt geprüft“. So wird aus einer einmaligen Schreibaufgabe ein kontrollierbarer Pflegeprozess.

Die technische Architektur übersichtlich beschreiben

Der Architekturteil sollte den Weg einer Anfrage bis zur Ausgabe der Website verständlich machen. Leserinnen und Leser müssen nicht jede Servereinstellung kennen, sollten aber die wichtigsten Komponenten und ihre Beziehungen erkennen können.

Infrastruktur und Hosting

Halten Sie den Hosting-Anbieter, den Tarif oder die Serverumgebung, die verwendete PHP-Version, die Datenbanktechnologie und relevante Speicher- oder Laufzeitgrenzen fest. Wenn mehrere Umgebungen existieren, führen Sie sie getrennt auf:

  • Produktivumgebung für die öffentlich erreichbare Website
  • Test- oder Staging-Umgebung für Änderungen und Prüfungen
  • Entwicklungsumgebung für lokale Arbeit

Ergänzen Sie, wie die Umgebungen voneinander unterschieden werden und ob Daten zwischen ihnen kopiert werden. Besonders wichtig sind Angaben zu Dateipfaden, Protokollen, Cron-Aufgaben und Serverzugriffen. Zugangsdaten selbst gehören nicht in die Dokumentation. Verweisen Sie stattdessen auf den Speicherort und die zuständige Berechtigungsrolle.

Domain, DNS und HTTPS

Dokumentieren Sie, bei welchem Anbieter die Domain verwaltet wird, wer als Verantwortlicher eingetragen ist und welche DNS-Einträge für Website, E-Mail oder externe Dienste erforderlich sind. Erklären Sie auch, wo Zertifikate verwaltet werden und ob ihre Erneuerung automatisch erfolgt.

Vermeiden Sie unklare Formulierungen wie „SSL ist aktiv“. Beschreiben Sie stattdessen, welche Domainvarianten funktionieren, wohin die Weiterleitungen führen und wie eine Prüfung nach einer DNS- oder Zertifikatsänderung erfolgt.

WordPress, Theme und Plugins

Listen Sie die WordPress-Version, das aktive Theme, ein mögliches Child-Theme und alle relevanten Plugins auf. Für jede Erweiterung sind mindestens folgende Angaben sinnvoll:

  • Name und Zweck der Erweiterung
  • aktuelle Version und Update-Verantwortung
  • Abhängigkeiten zu anderen Plugins oder Themes
  • kritische Einstellungen und externe Verbindungen
  • Folgen einer Deaktivierung oder Entfernung

Eine bloße Aufzählung reicht nicht aus. Beschreiben Sie, welche Funktion von einer Erweiterung abhängt. Ein Formular-Plugin kann beispielsweise mit einem E-Mail-Dienst verbunden sein, während ein Caching-Plugin die Auslieferung und das Verhalten nach Änderungen beeinflusst.

Individuelle Anpassungen und Code nachvollziehbar dokumentieren

Viele WordPress-Projekte enthalten Anpassungen, die in keiner sichtbaren Oberfläche erklärt werden. Dazu gehören Funktionen in der functions.php, eigene Plugins, Hooks, Shortcodes, Template-Overrides, CSS-Regeln, JavaScript, REST-Schnittstellen und serverseitige Weiterleitungen.

Dokumentieren Sie für jede individuelle Anpassung:

  • den technischen Speicherort oder das Repository
  • den Zweck und das erwartete Verhalten
  • die betroffenen Seiten, Inhaltstypen oder Benutzerrollen
  • Abhängigkeiten zu Plugins, APIs oder Datenfeldern
  • mögliche Risiken bei Updates
  • die zuständige Person oder das zuständige Team

Beschreiben Sie nicht nur, was der Code tut, sondern auch, warum er existiert. Ein Filter, der eine Ausgabe verändert, kann sonst später als überflüssig entfernt werden. Ebenso sollte klar sein, ob Änderungen direkt auf dem Server verboten sind und über welches Versionskontroll- oder Deployment-Verfahren sie veröffentlicht werden.

Datenmodell und wichtige Inhalte

Wenn die Website eigene Inhaltstypen, Taxonomien, benutzerdefinierte Felder oder wiederverwendbare Blöcke verwendet, gehören diese in die Dokumentation. Erklären Sie, wofür sie gedacht sind, welche Felder erforderlich sind und wo die Inhalte im Frontend erscheinen.

Für Redaktionen ist außerdem hilfreich, typische Beziehungen zu beschreiben: etwa die Verbindung eines Veranstaltungsbeitrags mit einem Standort oder die Zuordnung eines Produkts zu mehreren Kategorien. Diese Angaben verhindern Fehleingaben und erleichtern die Einarbeitung.

Betrieb, Updates und Backups dokumentieren

Die betriebliche Dokumentation sollte so geschrieben sein, dass eine verantwortliche Person eine Aufgabe sicher durchführen kann. Vermeiden Sie dabei pauschale Anweisungen wie „regelmäßig aktualisieren“. Legen Sie fest, was geprüft wird, in welcher Reihenfolge und woran ein erfolgreiches Ergebnis erkennbar ist.

Update-Prozess

Ein sinnvoller Update-Ablauf kann folgende Schritte enthalten:

  1. Änderung ankündigen und betroffene Verantwortliche informieren.
  2. Prüfen, ob ein aktuelles Backup vorhanden und nutzbar ist.
  3. Updates möglichst zuerst in einer Testumgebung einspielen.
  4. Wichtige Funktionen wie Anmeldung, Suche, Formulare, Medien und Checkout prüfen, sofern vorhanden.
  5. Änderungen in einer kurzen Versions- oder Wartungsnotiz festhalten.
  6. Produktivsystem aktualisieren und anschließend eine Funktionskontrolle durchführen.

Dokumentieren Sie auch, wann ein Update verschoben werden darf. Ein zeitlicher Aufschub kann bei einer inkompatiblen Erweiterung sinnvoll sein, sollte aber begründet, befristet und mit einer Aufgabe zur Nachprüfung versehen werden.

Backup und Wiederherstellung

Ein Backup ist nur dann hilfreich, wenn bekannt ist, was gesichert wird und wie die Wiederherstellung funktioniert. Halten Sie deshalb fest:

  • welche Dateien und Datenbanken einbezogen werden
  • wie häufig Sicherungen erstellt werden
  • wie lange sie aufbewahrt werden
  • wo sie gespeichert und gegen unbefugten Zugriff geschützt werden
  • wer eine Wiederherstellung auslösen darf
  • wie die Website nach der Wiederherstellung geprüft wird

Behaupten Sie nicht, Backups seien zuverlässig, wenn ihre Wiederherstellbarkeit nie geprüft wurde. Eine vertrauenswürdige Dokumentation trennt zwischen „Sicherung wird erstellt“ und „Wiederherstellung wurde zu einem bestimmten Zeitpunkt erfolgreich geprüft“. Falls noch kein Wiederherstellungstest stattgefunden hat, sollte dies offen als Aufgabe vermerkt werden.

Sicherheit, Datenschutz und Berechtigungen festhalten

Technische Dokumentation darf keine zusätzlichen Sicherheitsrisiken erzeugen. Speichern Sie daher keine Passwörter, API-Schlüssel, privaten Schlüssel oder vollständigen geheimen Tokens im Dokument. Verweisen Sie auf einen sicheren Tresor und dokumentieren Sie die Rollen, nicht die geheimen Werte selbst.

Für die Benutzerverwaltung sollten Sie erklären, welche Rollen existieren und welche Aufgaben sie benötigen. Prüfen Sie, ob Administratorrechte wirklich erforderlich sind. Halten Sie außerdem fest, wie ausgeschiedene Mitarbeitende entfernt werden, wie externe Zugänge zeitlich begrenzt sind und wer regelmäßige Berechtigungsprüfungen durchführt.

Auch Datenschutzbezüge gehören in den technischen Überblick. Listen Sie beispielsweise Formulare, Analysewerkzeuge, eingebundene Schriftarten, Karten, Videos, Newsletter-Dienste und Zahlungsanbieter auf, sofern sie personenbezogene Daten verarbeiten oder Verbindungen zu externen Systemen aufbauen. Die technische Dokumentation ersetzt keine rechtliche Prüfung, schafft aber eine wichtige Grundlage für diese Prüfung.

Sicherheitsvorfälle und Notfallkontakte

Ein Notfallabschnitt sollte sachlich und handlungsorientiert sein. Beschreiben Sie, wer bei einem Ausfall informiert wird, wo Protokolle zu finden sind und welche ersten Schritte zulässig sind. Dazu können das Sichern von Logdaten, das Sperren eines kompromittierten Zugangs oder das Aktivieren einer Wartungsseite gehören.

Vermeiden Sie unbestimmte Aussagen wie „bei einem Angriff sofort alles zurücksetzen“. Die richtige Reaktion hängt vom Vorfall ab. Dokumentieren Sie stattdessen Eskalationswege und verweisen Sie auf ein abgestimmtes Sicherheitsverfahren.

Dokumentation verständlich und wartbar schreiben

Technische Genauigkeit und gute Lesbarkeit gehören zusammen. Verwenden Sie kurze Absätze, aussagekräftige Überschriften und eindeutige Begriffe. Erklären Sie Fachwörter beim ersten Auftreten oder verlinken Sie auf ein internes Glossar. Eine neue Person sollte erkennen können, welche Schritte zwingend sind und welche Informationen nur zur Orientierung dienen.

Jeder größere Abschnitt sollte eine verantwortliche Rolle und ein Prüfdatum besitzen. Eine einfache Kopfzeile mit „Verantwortlich“, „Version“, „zuletzt geprüft“ und „nächste Prüfung“ erhöht die Verlässlichkeit. Änderungsnotizen helfen dabei, nachvollziehbar zu bleiben, ohne ältere Versionen vollständig im Hauptdokument zu wiederholen.

Geeignete Ablage und Verlinkung

Wählen Sie einen Speicherort, der für die vorgesehenen Personen erreichbar ist, aber nicht öffentlich ausliefert. Eine zentrale Wissensdatenbank oder ein versionskontrolliertes Repository kann geeignet sein. Entscheidend sind klare Berechtigungen, eine nachvollziehbare Struktur und ein Verfahren für Änderungen.

Verlinken Sie nur auf stabile interne Ziele und ergänzen Sie bei wichtigen Informationen einen kurzen Kontext. Ein Link mit der Bezeichnung „hier“ ist weniger hilfreich als „Anleitung zur Wiederherstellung der Produktionsdatenbank“. Prüfen Sie Links und Screenshots regelmäßig, weil sich Verwaltungsoberflächen verändern können.

Praktische Struktur für eine WordPress-Dokumentation

Die folgende Gliederung eignet sich als Ausgangspunkt. Sie kann je nach Projekt verkürzt oder erweitert werden:

  1. Dokumentinformationen: Zweck, Zielgruppe, Verantwortliche, Version und Prüfdatum.
  2. Systemüberblick: Domain, Hosting, Umgebungen und zentrale Abhängigkeiten.
  3. Architektur: Server, Datenbank, WordPress, Theme, Plugins und externe Dienste.
  4. Inhalte und Datenmodell: Inhaltstypen, Felder, Taxonomien und wichtige redaktionelle Beziehungen.
  5. Entwicklung: Repository, lokale Einrichtung, Code-Anpassungen, Tests und Deployment.
  6. Betrieb: Updates, Backups, Monitoring, Wartungsfenster und wiederkehrende Aufgaben.
  7. Sicherheit: Rollen, Zugänge, Geheimnisse, Datenschutzbezüge und Vorfallmanagement.
  8. Fehlerbehebung: typische Symptome, erste Prüfungen, Logs und Eskalationswege.
  9. Übergabe: offene Punkte, Kontakte, Abnahmen und nächste Wartungstermine.

Jeder Abschnitt sollte einen klaren Zweck erfüllen. Wenn eine Information weder für Betrieb, Entwicklung, Sicherheit, Redaktion noch Übergabe relevant ist, gehört sie möglicherweise nicht in die Hauptdokumentation. Details können in verknüpfte Unterseiten ausgelagert werden.

Qualität prüfen und Dokumentation aktuell halten

Eine Dokumentation ist kein fertiges Endprodukt, sondern Teil des Website-Betriebs. Legen Sie feste Auslöser für eine Aktualisierung fest: WordPress- oder PHP-Wechsel, Theme-Wechsel, neue Schnittstellen, Änderungen an Benutzerrollen, Hosting-Migrationen und Sicherheitsvorfälle.

Führen Sie bei der Prüfung nicht nur einen sprachlichen Korrekturlauf durch. Lassen Sie eine andere Person einen wichtigen Ablauf anhand der Dokumentation nachvollziehen. Dabei zeigt sich, ob Schritte fehlen, Berechtigungen unklar sind oder Begriffe unterschiedlich verwendet werden. Besonders wertvoll ist eine Übergabe an eine Person, die nicht an der ursprünglichen Umsetzung beteiligt war.

Markieren Sie veraltete Informationen nicht einfach als aktuell. Kennzeichnen Sie offene Punkte, nennen Sie die zuständige Rolle und geben Sie ein realistisches Prüfdatum an. So bleibt sichtbar, wo noch Unsicherheit besteht.

Häufige Fehler beim Erstellen einer technischen Dokumentation

  • Zu viele Geheimnisse im Dokument: Passwörter und Schlüssel werden aus Bequemlichkeit direkt eingefügt.
  • Nur der Idealablauf wird beschrieben: Fehlerfälle, Wiederherstellung und Eskalation fehlen.
  • Plugins werden nur aufgelistet: Zweck, Abhängigkeiten und Folgen einer Deaktivierung bleiben offen.
  • Individueller Code ist unsichtbar: Anpassungen werden nicht erklärt oder liegen außerhalb einer nachvollziehbaren Versionsverwaltung.
  • Die Dokumentation wird einmalig erstellt: Nach späteren Änderungen stimmt sie nicht mehr mit dem System überein.
  • Die Zielgruppe wird ignoriert: Redakteure erhalten Serverdetails, während technische Verantwortliche wichtige Betriebsinformationen vermissen.
  • Ungeprüfte Behauptungen werden als Fakten formuliert: Backups, Sicherheitsmaßnahmen oder Automatisierungen werden angenommen, ohne sie nachzuweisen.

Diese Fehler lassen sich durch klare Verantwortlichkeiten, kurze Prüfroutinen und eine Trennung von Überblick und Detailwissen vermeiden.

FAQ

Wie umfangreich sollte eine WordPress-Dokumentation sein?

Der Umfang richtet sich nach der Komplexität und dem Risiko der Website. Eine kleine Website benötigt weniger Detailtiefe als ein Shop, ein Mitgliederbereich oder eine Plattform mit mehreren Schnittstellen. Dokumentieren Sie alle Informationen, die für Betrieb, Sicherheit, Fehlerbehebung und Übergabe notwendig sind.

Wo sollten Zugangsdaten gespeichert werden?

Zugangsdaten gehören in einen geeigneten Passwortmanager oder einen vergleichbar geschützten Tresor. In der technischen Dokumentation sollten Sie nur den Speicherort, die zuständige Rolle und den Ablauf für eine Berechtigungsvergabe beschreiben.

Wie oft muss eine Dokumentation aktualisiert werden?

Aktualisieren Sie sie nach jeder Änderung, die Architektur, Betrieb, Sicherheit oder Zuständigkeiten beeinflusst. Zusätzlich ist eine regelmäßige Prüfung sinnvoll. Das konkrete Intervall sollte zur Änderungsfrequenz und zur Bedeutung der Website passen.

Soll die Dokumentation auch redaktionelle Abläufe enthalten?

Ja, sofern redaktionelle Abläufe technische Funktionen oder Datenstrukturen betreffen. Beschreiben Sie beispielsweise die Nutzung eigener Inhaltstypen, Pflichtfelder, Medienanforderungen und wichtige Veröffentlichungsprüfungen. Reine Stilrichtlinien können in einem separaten Redaktionshandbuch liegen.

Was gehört in eine Notfalldokumentation?

Sie sollte Zuständigkeiten, Kommunikationswege, erste sichere Prüfungen, wichtige Protokolle, Backup-Informationen und Eskalationsregeln enthalten. Vermeiden Sie riskante Schnellmaßnahmen, wenn ihre Folgen nicht bekannt sind, und halten Sie fest, wer Entscheidungen freigeben darf.

Wie dokumentiere ich ein Plugin, dessen Funktion nicht vollständig bekannt ist?

Beschreiben Sie zunächst die beobachtete Nutzung, betroffene Seiten und erkennbare Einstellungen. Kennzeichnen Sie unbekannte Punkte ausdrücklich und planen Sie eine Prüfung ein. Entfernen oder deaktivieren Sie die Erweiterung nicht allein aufgrund unvollständiger Dokumentation.

Ist eine technische Dokumentation auch für kleine Websites sinnvoll?

Ja. Auch eine kleine Website kann von einem Dienstleisterwechsel, einem verlorenen Zugang oder einer fehlerhaften Aktualisierung betroffen sein. Eine kompakte Übersicht mit Hosting, Domain, Erweiterungen, Backups, Zuständigkeiten und Notfallkontakten bietet bereits großen Nutzen.

Fazit: WordPress technische Dokumentation erstellen

Wenn Sie eine technische WordPress-Dokumentation erstellen, sollten Sie nicht möglichst viele Details sammeln, sondern die richtigen Informationen verlässlich zugänglich machen. Beginnen Sie mit einer geprüften Bestandsaufnahme, erklären Sie Architektur und Abhängigkeiten, dokumentieren Sie individuelle Anpassungen und beschreiben Sie wiederkehrende Betriebs- und Notfallabläufe.

Trennen Sie sensible Zugangsdaten von der Dokumentation, weisen Sie Verantwortlichkeiten zu und markieren Sie ungeklärte Punkte offen. Durch feste Prüfzeitpunkte bleibt das Dokument aktuell. So wird die technische Dokumentation zu einem praktischen Arbeitsmittel, das Übergaben erleichtert, Ausfallrisiken reduziert und den langfristigen Betrieb der WordPress-Website unterstützt.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre, wie deine Kommentardaten verarbeitet werden.