Dokumentation hat einen Lebenszyklus. Es wird geschaffen, um einen Bedarf zu decken, bleibt zuverlässig, wenn sich Dinge ändern, und wird schließlich ausgemustert, wenn der Bedarf nicht mehr besteht. Dokumentation als etwas zu behandeln, das einmal geschrieben und dann unbewahrt gelassen wird, ist der zuverlässigste Weg zu einer Wissensdatenbank, der Leser – und zunehmend auch die KI-Systeme, die in ihrem Namen antworten – aufhören zu vertrauen.
Dieser Artikel beschreibt jede Phase des Dokumentationslebenszyklus und die Praktiken, die eine Wissensbasis über die Zeit gesund halten.
Phase 1: Erstellen
Die Erstellung beginnt nicht, wenn man ein leeres Dokument öffnet, sondern wenn man einen Bedarf identifiziert. Ein Dokumentationsbedarf besteht, wenn Leser ein Ziel ohne Hilfe nicht erreichen können – und diese Hilfe existiert noch nicht in Ihrer Wissensbasis.
Identifizieren Sie, was geschrieben werden muss
Die zuverlässigsten Signale für Dokumentationslücken sind Supportanfragen, Nutzerfeedback und Suchanfragen, die keine Ergebnisse liefern. Wenn dein Support-Team dieselbe Frage zehnmal pro Woche beantwortet, braucht diese Frage einen Artikel. Wenn Leser nach einem Begriff suchen, der nicht in Ihrer Wissensdatenbank vorkommt, muss dieser Begriff dort sein.
Behandle deine Support-Warteschlange als Dokumentationsrückstau. Jede Frage, die durch Dokumentation beantwortet werden sollte – es aber nicht war –, ist eine Lücke, die es zu schließen gilt.
Schreiben Sie mit einem definierten Umfang
Definieren Sie vor dem Schreiben genau, was der Aufsatz behandeln wird und was nicht. Ein definierter Umfang verhindert, dass Artikel unbegrenzt wachsen, und konzentriert sie auf ein einziges Leserziel. Schreiben Sie den Umfang in einem Satz auf, bevor Sie beginnen: "Dieser Artikel erklärt, wie man [Aufgaben] für [Zielgruppe] bestellt, beginnend ab [Voraussetzungszustand]."
Wenn du diesen Satz nicht klar formulieren kannst, hast du noch nicht genug Klarheit darüber, was du schreibst. Klären Sie zuerst den Umfang.
Überprüfung vor der Veröffentlichung
Jeder Artikel sollte vor der Veröffentlichung von mindestens einer weiteren Person geprüft werden – idealerweise jemand mit Fachwissen, der die Genauigkeit überprüfen kann, und jemand, der mit dem Thema nicht vertraut ist und die Klarheit überprüfen kann. Diese beiden Rezensenten erkennen unterschiedliche Arten von Problemen. Eine Person, die sowohl Experte als auch mit der Perspektive des Lesers nicht vertraut ist, ist kein Ersatz für beides.
Phase 2: Pflege
Wartung ist die Phase, die die meisten Wissensdatenbanken vernachlässigen und die am meisten vernachlässigt werden. Eine nicht gepflegte Wissensdatenbank bleibt nicht neutral – sie verschlechtert sich aktiv. Ungenaue Artikel werden gelesen und befolgt. Veraltete Schritte führen die Leser in die falsche Richtung. Begriffe, die nicht mehr das bedeuten, was sie früher bedeuteten, sorgen für Verwirrung.
Dieses Risiko ist nicht mehr auf menschliche Leser beschränkt. Ein KI-Assistent, der einen veralteten Artikel zitiert, kann veraltete oder falsche Informationen für jemanden aufdecken, der diesen Artikel nie selbst durch Suche oder Navigation gefunden hätte – oft mit derselben Sicherheit präsentiert wie korrekter Inhalt. Eine nicht gepflegte Wissensbasis verliert nicht einfach stillschweigend das Vertrauen der Leser, die auf alte Artikel stoßen; Es kann Fehler aktiv in jedem System verteilen, das sie abruft und zusammenfasst.
Erstellen Sie einen Überprüfungsplan auf Basis von zwei Variablen, nicht nur einer
Setzen Sie jedem Artikel ein Bewertungsdatum zu. Das geeignete Intervall hängt von zwei Faktoren ab, die zusammenarbeiten, nicht nur von einem:
- Wie häufig sich der zugrundeliegende Inhalt ändert. Artikel über sich schnell verändernde Funktionen müssen möglicherweise vierteljährlich überprüft werden; Fundamentale konzeptuelle Artikel benötigen möglicherweise nur eine jährliche Überprüfung.
- Inhaltstyp. Ein Referenzartikel (wie eine API oder eine Parameterliste) wird meist in dem Moment veraltet, in dem sich ein zugrundeliegendes System ändert, und sollte im gleichen Rhythmus wie der Release-Zyklus dieses Systems überprüft werden. Ein konzeptioneller Artikel, der ein stabiles mentales Modell erklärt, kann sicher länger zwischen den Übersichtsarbeiten vergehen. Ein Artikel zur Fehlerbehebung sollte immer wieder durchgelesen werden, sobald das beschriebene Symptom seine Form ändert – selbst wenn das zugrundeliegende Merkmal auf dem Papier nicht verändert wurde.
Setze Erinnerungen für Prüfungen in dein Workflow-System. Wenn ein Bewertungstermin ansteht, prüft der Artikelbesitzer, ob der Inhalt noch korrekt ist, und aktualisiert ihn, falls nicht. Wenn es korrekt ist, setzen sie das Überprüfungsdatum zurück und machen weiter. Das dauert Minuten für einen Artikel, der sich nicht verändert hat, und nur Stunden, wenn bedeutende Aktualisierungen nötig sind.
Verknüpfe Dokumentation mit Produktänderungen
Die zuverlässigste Methode, um sicherzustellen, dass die Dokumentation aktuell bleibt, ist, Dokumentationsupdates als Teil des Produktrelease-Prozesses und nicht als nachträgliche Idee zu machen. Wenn sich eine Funktion ändert, ändert sich auch die Dokumentation für diese Funktion gleichzeitig – nicht Wochen später, wenn jemand die Diskrepanz bemerkt.
Dies erfordert eine Beziehung zwischen dem Dokumentationsteam und demjenigen, der die Produktveröffentlichungen verwaltet. Der Prozess muss nicht komplex sein: Ein gemeinsamer Checklistenpost, der "Dokumentation aktualisiert" vor dem Versand einer Veröffentlichung lautet, reicht aus.
Reagieren Sie auf Feedback
Leserfeedback – sei es durch Bewertungen, Kommentare oder Support-Tickets – ist Ihr direktes Signal, dass ein Artikel Aufmerksamkeit verdient. Ein Artikel, der regelmäßig schlechte Bewertungen erhält oder Nachfragen zur Unterstützung generiert, sagt Ihnen etwas. Untersuche es.
Beachten Sie auch Signale, die über direktes Feedback hinausgehen: Eine steigende Suchanzahl, die auf einen Artikel landen, aber sofort von einer Wiederholung gefolgt wird (was darauf hindeutet, dass der Artikel die Frage nicht beantwortet hat), oder eine deutliche Veränderung in der Häufigkeit, wie ein KI-Assistent oder eine Suchmaschine den Artikel zitiert, kann beide auf ein Qualitätsproblem hinweisen, bevor ein einzelner Leser sich beschwert.
Warte nicht darauf, dass sich das Feedback sammelt. Ein einzelner Leserkommentar, der sagt: "Schritt 4 funktioniert nicht", reicht aus, um eine Überprüfung auszulösen.
Zeigen Sie den Lesern, dass der Artikel gepflegt wird
Ein sichtbares "zuletzt aktualisiertes" Datum und – bei bedeutenden Änderungen – eine kurze Notiz zu den Änderungen stärken das Vertrauen der Leser auf eine Weise, wie es ein unsichtbar gepflegter Artikel nicht kann. Leser (und Rezensenten) vertrauen eher einem Artikel, der sichtbare Anzeichen von Pflege zeigt, als einem, der keinerlei Signale in die eine oder andere Richtung zeigt.
Phase 3: Ruhestand (oder Konsolidierung)
Die Dokumentationspensionierung ist der am wenigsten geübte Teil des Lebenszyklus, aber sie ist genauso wichtig wie Erstellung und Pflege. Ein Artikel über eine veraltete Funktion, einen Prozess, der nicht mehr existiert, oder eine Produktversion, die nicht mehr unterstützt wird, ist nicht neutral – er ist irreführend. Leser, die sie finden und folgen, werden auf Probleme oder Fehler stoßen und das Vertrauen in Ihre gesamte Dokumentation verlieren. Schlimmer noch: Ein KI-System, das sich nicht bewusst ist, dass der Artikel veraltet ist, könnte ihn unbegrenzt als aktuelle Tatsache zitieren.
Kandidaten für den Ruhestand identifizieren
Ein Artikel ist ein Kandidat für den Ruhestand, wenn:
- Das beschriebene Merkmal oder der Prozess existiert nicht mehr.
- Sie wurde durch einen neueren Artikel abgelöst, der dasselbe Thema genauer behandelt.
- Die Produktversion, auf die es zutrifft, wird nicht mehr unterstützt.
- Es erhält konstant niedrige Bewertungen und das zugrundeliegende Thema gilt nicht mehr.
- Analysen zeigen, dass es fast keinen Traffic erhält und das Thema nicht etwas ist, das die Leser brauchen.
Wisse, wann du konsolidieren solltest, statt in Rente zu gehen
Nicht jeder problematische Artikel sollte komplett eingestellt werden. Ein häufiges Szenario sind zwei Artikel, die in dasselbe Thema geraten sind – oft von verschiedenen Personen zu unterschiedlichen Zeiten geschrieben –, ohne dass einer sich irrt. Wenn dies geschieht, ist es meist richtig, sie zu einem einzigen, autoritativen Artikel zusammenzufassen, anstatt einen zu löschen und den anderen zu behalten, da der erhaltene Artikel selbst unvollständig sein kann. Führen Sie die korrekten Inhalte beider zusammen, lassen Sie den Verlierer mit einer Weiterleitung zum zusammengeführten Ergebnis in den Ruhestand und notieren Sie die Konsolidierung in der Aktualisierungshistorie des erhaltenen Artikels.
Zieh dich würdevoll zurück
Einen Artikel zurückzuziehen bedeutet nicht immer, ihn sofort zu löschen. Wenn der Artikel für ältere Versionen noch relevant ist, archivieren Sie ihn mit einem klaren Hinweis oben, der erklärt, dass der Inhalt nur auf eine bestimmte Version zutrifft, und verlinken Sie auf die aktuelle Dokumentation.
Wenn der Artikel wirklich veraltet ist, entfernen Sie ihn – und richten Sie eine Weiterleitung von seiner URL zum aktuellsten relevanten Artikel ein. Ein Leser, der einen pensionierten Artikel mit einem Lesezeichen versehen hat, sollte an einem nützlichen Ort landen und nicht auf einem 404-Fehler. Eine Weiterleitung verhindert außerdem, dass eine Suchmaschine oder ein KI-System noch lange nach dem Verschwinden des Artikels einen toten Link aufzeigt.
Eigentum und Verantwortlichkeit
Ein Dokumentationszyklus funktioniert nur, wenn jemand dafür verantwortlich ist. Jeder Artikel sollte einen Eigentümer haben – eine Person, die für seine Genauigkeit und Aktualität verantwortlich ist. In einem kleinen Team kann eine Person alles besitzen. In einem größeren Team wird die Eigentümerschaft typischerweise nach Themenbereich oder Produktfeature verteilt.
Dokumentiere das Eigentum klar und halte es aktuell. Wenn sich die Eigentümerschaft ändert – weil jemand das Team verlässt oder die Verantwortung für einen Produktbereich verschiebt – aktualisieren Sie gleichzeitig die Dokumentation, die Eigentumsunterlagen. Nicht besessene Dokumentation wird zur veralteten Dokumentation.
Planen Sie die Lücke, nicht nur die Zuweisung: Wenn der Inhaber eines Artikels ausscheidet oder weitergeht und noch kein Nachfolger benannt wurde, sollte der Eigentümer automatisch auf einen festgelegten Rückfallplan zurückgreifen – typischerweise den Teamleiter oder den Eigentümer der Mutterkategorie – anstatt unzugewiesen zu bleiben, bis es jemand bemerkt. Ein Artikel ohne Eigentümer, auch nur vorübergehend, ist ein Artikel, der nicht überprüft wird.