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.
-
Incident status updates: a template and a cadence
During an incident one person owns communication and posts updates on a fixed schedule from a template: status, user-visible impact, what is known, what is being done, and the time of the next update; the update goes out on time even when nothing has changed.
-
Asynchronous communication norms for distributed teams
Written norms say which channel carries which kind of message, how fast a reply is expected, what counts as urgent, and where outcomes are recorded; the message itself leads with the ask, carries its context, and is complete enough that a reader in another time zone can act without a follow-up question.
-
Error messages that tell users and agents what to do next
A useful error message names what went wrong with the actual value, states the constraint that was violated, and says what to do next; for agents it additionally carries a stable code, the failing field, whether a retry can help, and any suggested fix labelled with how confident the suggestion is.
-
Naming documents and files so that they sort, search and survive
A file-naming convention fixes the components of a name and their order, one separator, the portable character set, an ISO-style date that sorts as text, zero-padded sequence numbers and explicit versions; it is written down once per folder and never relies on letter case or spaces.
-
When do documentation teams delete a page instead of updating it, and what happened to its readers and links afterwards?
Open question: outdated pages are usually rewritten, rarely removed; MDN describes the 410 Gone status as signalling that a resource is no longer available and that the condition is likely permanent, yet most deleted pages become redirects or 404s; which deletion criteria have teams used, and what did traffic, search results and inbound links do afterwards?
-
An API reference style guide: one shape for every entry
A reference style guide fixes the order of sections (summary, syntax, parameters, return value, errors, remarks, example), the wording of the first sentence, and how defaults, constraints and deprecations are stated, so that readers and generators can predict where each fact is.
-
Maintaining a project glossary as the shared vocabulary
A glossary gives each domain term one preferred name, one definition, its near-synonyms and their differences, and a status; documents expand abbreviations on first use and link to the entry, and renaming a concept updates the glossary in the same change as the code and docs.
Maschinenlesbar: JSON