Thema: technical-writing
-
Onboarding-Dokumentation: der Weg von einer frischen Maschine zu einer gemergten Änderung
Onboarding-Dokumentation ist ein einziger nummerierter Weg, der eine neue Person – Mensch oder Agent – von nichts Installiertem zu einer gemergten Änderung führt, nur mit dem, was schriftlich vorliegt; jede neue Person behebt, worüber sie gestolpert ist, und der Weg trägt einen Owner sowie ein Aktualitätsdatum.
-
Rechtfertigen FAQ-Seiten ihren Platz, und was bewahrt sie vor dem Veralten?
Offene Frage: Der Stilratgeber von GOV.UK verbietet FAQs auf GOV.UK mit der Begründung, dass von den Bedürfnissen der Nutzenden ausgehend geschriebene Inhalte sie nicht brauchen, während die Nielsen Norman Group argumentiert, dass FAQs einen Mehrwert liefern und Suche allein selten genügt; welche messbaren Ergebnisse, Eigentumsregeln und Prüfungen auf Veralterung haben Teams für FAQ-Seiten in technischer Dokumentation festgehalten?
-
Diagramme als Code mit Mermaid: was gut funktioniert und wo die Grenzen liegen
Mermaid rendert Diagramme aus Text innerhalb von Markdown, sodass Diagramme neben dem Code liegen, sich im Review als Diff zeigen und von GitHub sowie anderen Viewern dargestellt werden; die Grenzen liegen beim automatischen Layout, das sich nicht feinjustieren lässt, bei der Grösse, bei Unterschieden zwischen Renderer-Versionen und bei der Barrierefreiheit, die explizite Title- und Description-Schlüsselwörter braucht.
-
Ausgangstext schreiben, der sich gut übersetzen lässt
Ausgangstext für Oberflächen und Dokumentation lässt sich sauber übersetzen, wenn Sätze vollständige Einheiten sind, Strings nie aus Fragmenten zusammengesetzt werden, Plurale und Platzhalter über das Framework laufen und Redewendungen, Humor sowie kulturspezifische Bezüge weggelassen werden; die Einschränkungen ergeben sich daraus, wie gettext-artige Werkzeuge und Übersetzer arbeiten.
-
Ein Designdokument oder RFC schreiben, über das Reviewende entscheiden können
Ein Designdokument verdient eine Entscheidung, bevor Code geschrieben wird: zuerst das Problem, dann Ziele und Nicht-Ziele, eine Erklärung auf Leitfaden-Ebene und eine auf Referenz-Ebene, Alternativen mit den Gründen für ihre Ablehnung, Nachteile und eine ausdrückliche Liste offener Fragen; die Struktur folgt dem, was PEP 1, die Rust-RFC-Vorlage und Googles Designdokument-Praxis verlangen.
-
Statusmeldungen bei Vorfällen: eine Vorlage und ein Takt
Während eines Vorfalls übernimmt eine Person die Kommunikation und veröffentlicht Updates nach festem Zeitplan anhand einer Vorlage: Status, für Nutzende sichtbare Auswirkung, was bekannt ist, was unternommen wird, und der Zeitpunkt des nächsten Updates; das Update erscheint pünktlich, auch wenn sich nichts geändert hat.
-
Normen für asynchrone Kommunikation in verteilten Teams
Schriftlich festgehaltene Normen legen fest, welcher Kanal welche Art von Nachricht trägt, wie schnell eine Antwort erwartet wird, was als dringend gilt und wo Ergebnisse festgehalten werden; die Nachricht selbst beginnt mit dem Anliegen, trägt ihren Kontext und ist vollständig genug, dass eine lesende Person in einer anderen Zeitzone handeln kann, ohne nachfragen zu müssen.
-
Fehlermeldungen, die Nutzenden und Agenten sagen, was als Nächstes zu tun ist
Eine nützliche Fehlermeldung benennt, was mit dem tatsächlichen Wert schiefgegangen ist, nennt die verletzte Einschränkung und sagt, was als Nächstes zu tun ist; für Agenten trägt sie zusätzlich einen stabilen Code, das betroffene Feld, ob ein erneuter Versuch helfen kann, sowie jeden Korrekturvorschlag mit einer Kennzeichnung, wie sicher der Vorschlag ist.
-
Dokumente und Dateien so benennen, dass sie sich sortieren, finden und dauerhaft bestehen lassen
Eine Namenskonvention für Dateien legt die Bestandteile eines Namens und ihre Reihenfolge fest, ein Trennzeichen, den portablen Zeichensatz, ein Datum im ISO-Stil, das sich als Text sortieren lässt, mit Nullen aufgefüllte Sequenznummern und explizite Versionen; sie wird einmal pro Ordner niedergeschrieben und verlässt sich nie auf Gross-/Kleinschreibung oder Leerzeichen.
-
Wann löschen Dokumentationsteams eine Seite statt sie zu aktualisieren, und was geschah anschliessend mit deren Leserschaft und Links?
Offene Frage: Veraltete Seiten werden meist umgeschrieben, selten entfernt; MDN beschreibt den Status 410 Gone als Signal, dass eine Ressource nicht mehr verfügbar ist und dieser Zustand wahrscheinlich dauerhaft ist, doch die meisten gelöschten Seiten werden zu Weiterleitungen oder 404s; welche Löschkriterien haben Teams verwendet, und was geschah anschliessend mit Traffic, Suchergebnissen und eingehenden Links?
-
Ein Stilleitfaden für API-Referenzen: eine Form für jeden Eintrag
Ein Stilleitfaden für Referenzen legt die Reihenfolge der Abschnitte fest (Zusammenfassung, Syntax, Parameter, Rückgabewert, Fehler, Anmerkungen, Beispiel), den Wortlaut des ersten Satzes und wie Standardwerte, Einschränkungen und Veraltungen angegeben werden, damit Lesende und Generatoren vorhersagen können, wo jede Angabe steht.
-
Ein Projektglossar als gemeinsames Vokabular pflegen
Ein Glossar gibt jedem Fachbegriff einen bevorzugten Namen, eine Definition, seine Beinahe-Synonyme mitsamt deren Unterschieden und einen Status; Dokumente schreiben Abkürzungen bei der ersten Verwendung aus und verlinken auf den Eintrag, und das Umbenennen eines Konzepts aktualisiert das Glossar in derselben Änderung wie Code und Dokumentation.
Maschinenlesbar: JSON