Schaffung einer Dokumentationskultur

Was ist Dokumentation? Und was macht es?

Eine der wichtigsten Aufgaben der Dokumentation ist die Anleitung unserer Benutzer. Das Lesen von Dokumenten ist ein entscheidender Teil der Benutzererfahrung. Sie können sich die Dokumentation so vorstellen, dass sie mit Kommentaren im Code beginnt. Anschließend erklimmen Sie die Leiter durch Endbenutzer-Produkthandbücher und Funktionskarten, Installations-, Benutzer-Onboarding- und QuickStart-Anleitungen, Rezepte und Anwendungsbeispiele sowie ausführlichere Tutorials.

Darüber hinaus sprechen Sie möglicherweise immer noch mit Hauptnutzern, oft aber auch mit potenziellen Kunden. Eine kohärente Dokumentation erzählt auch eine technische und geschäftliche Geschichte Ihrer Produkte im Kontext. Es geht um die Vorteile Ihrer Produkte, die Differenzierung von der Konkurrenz und die Etablierung einer Vordenkerrolle.

Eine gute Dokumentationskultur betrachtet Dokumente als einen grundlegenden Aspekt sowohl des Marketings als auch des Produkts.

Warum ist eine gute Dokumentation so wichtig?

Eine gute Dokumentation sorgt für:

• Besseres Onboarding, sowohl für Kunden als auch für neue Mitarbeiter. Gute erste Eindrücke von Dokumenten führen zu guten ersten Eindrücken Ihrer Produkte.
• Schnellere Fehlerbehebung, da alles aufgeschrieben wird, was zur Bindung von Benutzern und Kunden beiträgt.
• Höhere Produktivität für Kunden und Ihr Support-Team. Gute Dokumente führen zu guten Produkterlebnissen. Sie verhindern Fehler und Verwirrung auf Seiten der Kunden (reduzieren den Supportaufwand) und ermöglichen eine schnellere Problemlösung.
• Besseres Änderungsmanagement, da gute Dokumente den Verlauf detailliert beschreiben, die Auswirkungen aufzählen und Sie bei der Bereitstellung neuer Funktionen unterstützen, ohne Benutzer oder Supportmitarbeiter zu belasten.

Es sorgt auch für eine bessere Kommunikation und weniger Arbeitsverschwendung. Pro eine aktuelle Studie der Cornell University von Fachkräften, die in verteilten Teams arbeiten:

• 61 % geben an, dass es schwierig sein kann, herauszufinden, woran ihre Kollegen arbeiten.
• 44 % sagen, dass isolierte digitale Medientools es schwierig machen, zu erkennen, ob Arbeit dupliziert wird.
• 62 % gaben an, dass ihnen Gelegenheiten fehlten, mit ihren Kollegen zusammenzuarbeiten und bessere Ergebnisse zu erzielen.

Schlechte Dokumentation ist hier Teil des Problems – und zwar im Wesentlichen ein Problem der Kommunikation. Eine gute Dokumentation kann, sofern sie sorgfältig gepflegt wird, Kommunikationssilos auflösen, verschwendete Arbeit vermeiden und Ihren Mitarbeitern helfen, viel besser zusammenzuarbeiten.

Was macht Dokumentation gut oder schlecht?

Eine gute Dokumentation ist:

• Zentralisiert auf einer Plattform: Fehlerhafte Dokumente sind fragmentiert und schwer zu finden und abzugleichen.
• Einfach zu verstehen: Gute Dokumente minimieren den Gebrauch von Fachjargon und halten die Sprache einfach (nicht jeder spricht fließend Englisch).
• Auf den Punkt gebracht; Es erzählt Ihnen nicht eine ganze Geschichte, bevor es Ihnen sagt, was Sie tun müssen und wonach Sie eigentlich suchen.
• Gute Optik: Menschen schauen von Natur aus auf Dinge, die schön anzusehen sind. Wir wollen sie uns genauer ansehen und wir wollen sie länger betrachten.
• Leicht zu lesen: Wenn Ihre Dokumentation schwer zu lesen ist, werden die Leute nicht so viel Zeit damit verbringen, sie sich anzusehen, wie sie es tun werden, wenn Sie eine sehr schön gestaltete, übersichtliche Dokumentation mit interessanten Dingen zum Anschauen haben.
• Vollständig, genau und aktuell: Es gibt nichts Schlimmeres als undokumentierte Produktfunktionen oder Dokumente voller Ungenauigkeiten.
• Enthält Datum und Autor: Wenn es Genauigkeitsprobleme gibt, wissen wir, wann sie aufgetreten sind und wie sie entstanden sind. Wir wissen auch, wie alt diese Dokumentation ist, wenn wir auf einen Fehler stoßen.
• Spricht die richtige Zielgruppe an: Wenn Sie sich an den Endbenutzer wenden, stellen Sie sicher, dass dieser die Person ist, die diese Informationen erhält. Wenn Sie sich an Administratoren wenden, stellen Sie sicher, dass Sie ihnen mitteilen, welche Informationen sie wissen müssen.
• Frei von Annahmen darüber, was Benutzer wissen oder tun können. Gute Dokumente verweisen Benutzer auf einführende Ressourcen und Leitfäden, die ihnen bei der Vorbereitung helfen und ihnen den Einstieg in eine gute Erfahrung mit Ihrem Produkt ermöglichen. Schlechte Dokumente setzen in der Regel viel Vorwissen voraus. Das Schlimmste (und das haben wir alle gesehen) scheint so geschrieben zu sein, dass nur die Kerningenieure, die am Projekt arbeiten, sie verstehen können.

Woher kommen fehlerhafte Dokumente? Und was kosten sie?

Schlechte Dokumentationskulturen haben einige gemeinsame Merkmale:

• Dokumentation ist jedermanns Problem und niemandes Aufgabe.
• Experten (z. B. Entwickler) haben keinen Anreiz, bei der Erstellung und Verbesserung von Dokumenten mitzuhelfen.
• Die Organisation (Dokumentationsspezialisten) steht Experten nicht zur Verfügung, um beim Schreiben und Bearbeiten zu helfen.
• Es wird davon ausgegangen, dass Dokumente mit Projekten geliefert werden können, es werden jedoch keine Ressourcen oder Zeit bereitgestellt, um dies zu ermöglichen. Auch die Notwendigkeit, Dokumente auf dem neuesten Stand zu halten, ist nie realistisch eingeplant.
• Menschen horten Informationen – um die Arbeitsplatzsicherheit zu wahren oder einfach, weil es keinen disziplinierten Prozess gibt, um institutionelles Wissen zu extrahieren und in Dokumentation umzuwandeln.

Was kosten Dokumentationsfehler? Eine Menge. Laut einem aktuellen Artikel von ItGlueEs ist üblich, dass Mitarbeiter von Technologieunternehmen bis zu 20 % ihrer Zeit damit verbringen, nach Informationen über die Produkte ihres eigenen Unternehmens zu suchen. Wenn wir von einem durchschnittlichen Gehalt von 60.000 US-Dollar pro Jahr ausgehen, kostet die verlorene Zeit pro Mitarbeiter 13.760 US-Dollar, wobei die Opportunitätskosten (abhängig vom prognostizierten Mitarbeiterbeitrag) typischerweise viel höher sind.

Wie fängt man an, eine schlechte Dokumentenkultur zu beseitigen?

In einem Fallstudie von Google Im Jahr 2016 gaben 48 % der Google-Ingenieure an, dass schlechte Dokumentation ihr größtes Produktivitätsproblem sei. 50 % der SRE-Probleme führten auf Probleme mit der Dokumentation zurück.

Was für Google funktioniert hat, war die Änderung des Status quo. Sie machten die Dokumentation für ihre Ingenieure radikal einfacher. Sie haben ein System namens g3docs erstellt, das Folgendes tat:

• Entscheidungen entferntund stellt eine Möglichkeit dar, Dinge zu dokumentieren.
• Zentralisierung und Bereitstellung einer einzigen Informationsquelle und Dokumentationstools. G3docs hat seine Dokumente im Quellcode in Markdown gehostet, sodass seine Ingenieure ihre IDs behalten und gleichzeitig an der Dokumentation arbeiten konnten. Ihr Dokumentationssystem hat diesen Markdown automatisch in schöne HTML-Seiten gerendert.
• Nutzung der einzigen Quelle der Dokumentenwahrheit – Das g3docs-Team bildete Allianzen mit einflussreichen Ingenieuren, um die neuen Docs-Tools einzuführen, und arbeitete mit bestimmten Teams zusammen, um strategische Integrationen aufzubauen, sodass viele Projekte auf das zentralisierte Docs-Repo zurückgreifen konnten.
• Das Dokumentationssystem wurde offen veröffentlicht und iteriert damit jeder wusste, was los war.
• Hatte Teams mit gutem Beispiel vorangehen lassen. Anstatt die Teams zu zwingen, die Tools zu nutzen, wandten sie sich an einige ihrer einflussreichsten Mitarbeiter, um alle mit ins Boot zu holen.

Methoden zur Kulturveränderung

Kultur ist nicht unveränderlich. Wir können es ändern, aber Sie müssen ganz oben beginnen, jemanden auswählen, der es steuert, und es einfach machen.

• Beginnen Sie von oben: Beginnen Sie mit der Standardisierung und stärken Sie Ihre Mitwirkenden, indem Sie klarstellen, dass klares, prägnantes Schreiben die Erwartung aller ist. Stellen Sie dazu sicher, dass Ihre Vorgesetzten und Ihre Stakeholder mit gutem Beispiel vorangehen und qualitativ hochwertige Texte schreiben.
• Wählen Sie jemanden, der es fährt: Beauftragen Sie jemanden mit der Verwaltung der Dokumentation. Auch wenn es nicht der gesamte Job dieser Person ist, machen Sie es zur offiziellen Verantwortung einer anderen Person. Diese Person erstellt auch Vorlagen, Schulungen und jede andere Unterstützung, die zum Erstellen der Dokumentation erforderlich ist.
• Mach es einfach: Wählen Sie Tools, die sich in bestehende Arbeitsabläufe integrieren lassen. Lassen Sie Entwickler in ihrem Editor bleiben. Je mehr Sie es den Menschen ermöglichen, im Fluss zu bleiben, in dem sie sich befinden, desto mehr Arbeit werden sie leisten können. Und verwenden Sie eine Versionskontrolle wie Git, damit jeder problemlos einen Beitrag leisten kann, und stellen Sie sicher, dass jeder Zugriff hat.

Werkzeuge und Techniken

Dies sind einige Beispiele für Dokumentationstools, die ich wirklich liebe und die sehr beliebt sind:

• Markdown ist eine der beliebtesten Sprachen zum Schreiben von Dokumentationen. Die Read The Docs-Plattform ist wirklich großartig. Sie ermöglichen die folgenden zwei Dokumentationssysteme: mkdocs, ein schneller und einfacher Dokumentationsgenerator, und Sphinx, ein leistungsfähigerer Dokumentationsgenerator, der sich wirklich gut für die technische Dokumentation eignet.
• GitBook ist eine nette Plattform, wenn Sie etwas wollen, das nicht Open Source ist und etwas glänzender ist.
• Confluence, das meiner Meinung nach jeder für seine interne Dokumentation nutzt, ob man will oder nicht, ist ein wirklich robustes System, wenn auch nicht Open Source.

Einer der Gründe, warum Dinge wie mkdocs so beliebt sind, besteht darin, Ihren Mitwirkenden die Möglichkeit zu geben, ein System zu nutzen, das Beiträge von jedem zulässt: Sie ermöglichen es jedem, Beiträge zu leisten. Und heutzutage müssen Sie nicht einmal in der Lage sein, Markdown in einem Editor zu bearbeiten – Sie können GitHub oder GitLab verwenden. Ihre Inline-Editoren eignen sich hervorragend zum Bearbeiten von Dokumentationen.

Bieten Sie Schulungen zum Schreiben von Dokumenten an, wenn Ihr Team das Gefühl hat, nicht schreiben zu können oder keine guten technischen Redakteure zu sein. Dies ermöglicht es jedem, ein Gefühl der Verantwortung für die Dokumente zu entwickeln und stolz darauf zu sein, dass andere Ihre Dokumentation lesen. Schaffen Sie eine positive Feedbackschleife für Menschen, die sich in der Vergangenheit gegen das Schreiben von Dokumentationen gewehrt haben, und beschließen, mit dem Schreiben dieser Dokumentation zu beginnen. Stellen Sie sicher, dass Sie ihnen dafür danken, dass Sie ihnen sagen, dass sie großartige Arbeit geleistet haben, sodass sie es wieder tun möchten.

Wenn es nicht funktioniert? Es gibt ein paar Dinge, die wir tun können. Wir können den etwas energischeren Weg gehen und einfach keine Zusammenführungsanfragen akzeptieren, die keine Dokumentationsaktualisierungen enthalten. Gehen Sie davon aus, dass die Dokumentation genauso wichtig ist wie der Code. Sie können das Schreiben von Dokumenten auch zu einem offiziellen Bestandteil der Stellenbeschreibung eines jeden machen. Geben Sie jedem das Bedürfnis, die Dokumentation zu aktualisieren, und machen Sie den Leuten klar, dass die Leute Ihr Produkt auf diese Weise verwenden und wie sie es verstehen werden.