Häufige Fehler in von Ingenieuren verfassten Dokumenten und wie man sie behebt

In den letzten sechs Monaten hat sich unser Entwicklungsteam den „Docs-as-Code“-Ansatz zu eigen gemacht (mehr über unsere Reise erfahren Sie hier). ). Bei der regelmäßigen Überprüfung der von meinen Kollegen aus der Tech-Abteilung erstellten Dokumentation habe ich eine Liste der häufigsten Probleme zusammengestellt, die beim Schreiben technischer Dokumentation auftreten.

In dem Artikel zeige ich Ihnen, wie Sie diese Probleme mit den Tools des „Docs-as-Code“-Ansatzes beheben können.

Problem 1: „Das Verfassen von Dokumenten liegt nicht in unserer Verantwortung“

Der Umgang mit Dokumentation auf Ad-hoc-Basis ist für das gesamte Entwicklungsteam so, als würde man sich selbst ins Bein schießen. Wenn dem Team die Kapazität fehlt, ist das ein zwingender Grund, die Dokumentationspflege technologiegesteuerter und vorhersehbarer zu gestalten.

Fix:

• Integrieren Sie den „Docs-as-Code“-Ansatz in die Entwicklung der Dokumentation. Auf diese Weise können Sie die Dokumentation zusammen mit der Codebasis iterativ aktualisieren, ohne das Risiko einer Anhäufung technischer Schulden einzugehen.
• Entwickeln oder integrieren Sie einen Raum oder eine Plattform, die technische Dokumente darstellen und als zentrale Informationsquelle dienen kann.
• Nutzen Sie eine integrierte Entwicklungsumgebung (IDE). Mit einer IDE können Sie Plugins integrieren und benutzerdefinierte Skripte für die Dokumentationsentwicklung erstellen. ist ein ausgezeichnetes Werkzeug zum Schreiben von Dokumenten, aber vielleicht haben Sie auch Ihre Favoriten unter den Anwendungen.
• Installieren Sie ein Rechtschreibprüfungs-Plugin, um sich vor Tippfehlern zu schützen. Das Hinzufügen des Plugins zu Ihrer IDE ist ein schneller und einfacher Vorgang.
• Übernehmen Sie die internen Richtlinien, die speziell von Ihrem Unternehmen erstellt wurden, und berücksichtigen Sie dabei Erkenntnisse aus der Community für technische Redakteure (falls vorhanden), um einen standardisierten Ansatz für die Entwicklung der Dokumentation innerhalb des Unternehmens zu etablieren. Das Befolgen dieser Richtlinien vereinfacht den Dokumentationsprozess und spart Zeit bei der Überlegung, was und wie genau geschrieben werden soll.
• Automatisieren Sie Prüfungen auf der Grundlage der Richtlinien, um die Zeit für die Überprüfung von Dokumenten erheblich zu verkürzen oder zu eliminieren.
• Erstellen Sie Vorlagen für alles Mögliche und einigen Sie sich mit dem Team auf die Standardisierung von Dokumentationskomponenten.

Ich stelle Ihnen wertvolle Ressourcen zur Verfügung, die Ihr Selbstvertrauen bei der Arbeit mit technischer Dokumentation stärken. Ich glaube, dass diese Ressourcen umfassend genug sind, um Sie für den effektiven Umgang mit technischen Dokumenten zu rüsten:

• Der " " dient als umfassendes Handbuch für die Entwicklerdokumentation. Es deckt alles ab, was Sie über Formatierung, Zeichensetzung, Auflistung und das Hinzufügen von Codeblöcken wissen müssen. Dieses Handbuch reicht aus und war eine wertvolle Referenz für die Entwicklung unserer internen Richtlinien, von denen wir einige übernommen haben empfohlene Vorgehensweise.
• „ „ ist ein Buch, das jeder lesen muss, der mit Entwicklerdokumentation zu tun hat, egal ob er sie entwickelt, schreibt oder pflegt. Das Buch stellt mehrere renommierte und angesehene Autoren auf dem Gebiet des technischen Schreibens vor.

• " „ von Anne Gentle, einer technischen Autorin, ist ein praktischer Leitfaden, der die Dokumentationskultur in OpenStack veranschaulicht. Anhand praktischer Beispiele erklärt der Autor, warum Dokumentation in GitHub verwaltet werden sollte und wie man technologische Prozesse für eine effektive Dokumentation implementiert. Das Buch bietet auch wertvolle Informationen Einblicke in das Schreiben professioneller Dokumentation, unabhängig davon, ob Sie Entwickler oder technischer Redakteur sind.

• Ich werde auch interne Richtlinien zum Schreiben technischer Dokumentation erwähnen, die Vorlagen und Formatierungsregeln enthalten sollten. Solche Richtlinien gibt es in jedem Unternehmen. Typischerweise werden sie gemeinsam mit einem technischen Redakteur/Pionier und Entwicklerdokumentationsexperten entwickelt und entwickeln sich weiter, wenn die Dokumentationskultur innerhalb des Teams wächst.

Problem 2. Dokumentation alleine schreiben

Die alleinige Entwicklung der gesamten Dokumentation und deren anschließende Einreichung zur Überprüfung birgt das Risiko, dass redundante oder irrelevante Dokumentationen entstehen, die möglicherweise nicht dem beabsichtigten Zweck entsprechen.

Fix:

• Beginnen Sie immer mit einer Gliederung und teilen Sie diese mit Ihrem Teamleiter, Produktinhaber, technischen Redakteur oder einem anderen Kollegen, der bereit ist, seine Expertenmeinung abzugeben.
• Schreiben Sie Schritt für Schritt und weisen Sie Pull-Anfragen zur Überprüfung denselben oben genannten Kollegen zu.
• Sammeln Sie Feedback und bearbeiten Sie es.
• Betrachten Sie die Kommentare. Seien Sie vorsichtig mit dem Tonfall der Rezension, denn manchmal kann er hart sein, aber das ist lediglich eine Besonderheit des Rezensionsprozesses.
• Übersehen Sie nicht den Dokumentationsfluss. Nachfolgend ist der allgemeine Ablauf aufgeführt, der in unserem Unternehmen angewendet wird. Die Merkmale dieses Ablaufs können jedoch sowohl vom Entwicklungsteam als auch vom Unternehmen abhängen:

Problem 3. „Wer verstehen muss, wird verstehen“

Von Zeit zu Zeit höre ich von Teams: „Ich schreibe für das Entwicklungsteam“, „Wer es braucht, wird es verstehen“, „So hat sich das historisch in unserem Team entwickelt.“

Fachjargon und Anglizismen erfordern jedoch Angemessenheit und Konsistenz. Eine übermäßige Verwendung kann dazu führen, dass die Dokumentation den Notizen eines verrückten Ingenieurs ähnelt.

Verwenden Sie zur Dokumentation möglichst einfache Wörter und Strukturen. Eines der Hauptprinzipien ist das Schreiben zum Scrollen. Das Schreiben einer Dokumentation kann eine Herausforderung sein, da sie oft umfangreich ist, die Leser sie jedoch selten von Anfang bis Ende durchgehen. Stattdessen neigen sie dazu, zu scrollen oder die Stichwortsuche zu verwenden. Daher sollte der Text aus allen Teilen leicht verständlich sein.

Fix:

• Überprüfen Sie englische Begriffe und Fachjargon mithilfe von Wörterbüchern und aktuellen Normen (oder googeln Sie sie einfach). Wenn ein Wort im Wörterbuch vorhanden ist, schreiben Sie nach den Regeln Ihrer Sprachorthographie.
• Wenn das Wort in der Sprache nicht vorkommt, schreiben Sie es in der Originalsprache und geben Sie in Klammern eine Übersetzung in Ihre Sprache an.
• Fügen Sie das Wort zum Glossarbereich und Abkürzungen zur Liste der Abkürzungen und Akronyme hinzu. Dies ist besonders wichtig für „proprietäre“ Abkürzungen (egal wie viel über PO erwähnt oder geschrieben wird, seine Bedeutung ist immer noch eine der häufigsten Fragen beim Lesen der Dokumentation).
• Konsistenz – Halten Sie sich in der gesamten Dokumentation an den gewählten Schreibstil und die Abkürzungen (besser für alle verfügbaren Dokumentationen in Ihrem Unternehmen).
• Planen Sie die Dokumentennavigation sorgfältig. Es sollte eine schnelle Möglichkeit geben, den relevanten Abschnitt zu finden, ohne das gesamte Dokument lesen zu müssen. Daher ist es wichtig, den Inhalt sorgfältig mit klaren und prägnanten Überschriften zu strukturieren. Der Einfachheit und Bequemlichkeit halber sollten interne Dokumentationsvorlagen entwickelt werden.

Problem 4. Dokumentation gleichzeitig an mehreren Orten schreiben

Für die Dokumentation ist es von entscheidender Bedeutung, über eine einzige Quelle der Wahrheit zu verfügen – einen Ort, an dem Sie die erforderlichen Informationen finden können, ohne sich Gedanken über deren Richtigkeit machen zu müssen. Für unsere technische Dokumentation dient eine selbst entwickelte Plattform als solcher Raum. Die Vermeidung einer Fragmentierung der Dokumentation in verschiedenen Bereichen ist von entscheidender Bedeutung, um zu verhindern, dass jemand mit veralteten Informationen in die Irre geführt wird.

Fix:

• Bevor Sie technische Dokumentation irgendwo veröffentlichen, stellen Sie sicher, dass sie nicht woanders existiert, falls sich herausstellt, dass das Unternehmen mehrere Bereiche für den Wissensaustausch nutzt.
• Archivieren oder löschen Sie veraltete technische Dokumentation (sofern Sie Eigentümer sind). Wenn Sie Bedenken hinsichtlich einer vorzeitigen Löschung haben (z. B. aufgrund externer Links zur Seite), fügen Sie einen Hinweis hinzu, der besagt, dass die Seite veraltet ist, und den aktuellen Dokumentationsort gültiger Dokumente, wo weitere Aktualisierungen vorgenommen werden sollten.
• Wenn Sie auf wertvolle Informationen oder Erkenntnisse stoßen, fügen Sie diese der Dokumentation hinzu. Belassen Sie es nicht in Slack oder anderswo, insbesondere nicht in privaten Chats. Wissen, das es wert ist, geteilt zu werden!

Gepostet von Anna Goncharova