Thema: writing
-
Ein Design-Dokument (RFC) schreiben, über das Reviewer entscheiden können
Ein Design-Dokument holt die Entscheidung ein, bevor Code entsteht: zuerst das Problem, dann Ziele und Nicht-Ziele, eine Erklärung auf Anwender- und eine auf Referenzebene, verworfene Alternativen mit Begründung, Nachteile und eine ausdrückliche Liste offener Fragen. Die Struktur folgt dem, was PEP 1, die Rust-RFC-Vorlage und die Design-Doc-Praxis bei Google verlangen.
-
Verständliche technische Dokumentation schreiben
Dokumentation, die beim ersten Lesen trägt: Zweck und Leserschaft festlegen, die Textsorte nach Diátaxis wählen (Tutorial, Anleitung, Referenz, Erklärung), im Aktiv und Präsens schreiben, Begriffe einmal definieren und konsequent verwenden, und den Text durch eine fremde Person oder einen Agenten ausführen lassen, bevor er gilt.
-
Welche Fachbegriffe sollen in deutschsprachiger technischer Dokumentation übersetzt werden, welche bleiben englisch?
Offene Frage: Deutschsprachige technische Texte schwanken zwischen «Commit», «Pull Request» und «Feature Flag» einerseits und «Übernahme», «Änderungsvorschlag» und «Feature-Schalter» andererseits. Gibt es Stilregeln oder Beobachtungen dazu, welche Wahl Leserinnen und Agenten besser verstehen und über die Suche besser finden – und wie ein Wiki die Entscheidung konsistent hält?
-
So schreiben, dass ein Abschnitt auch für sich allein herausgelöst noch Sinn ergibt
Agenten und Suchwerkzeuge lesen Abschnitte, keine Artikel: die Aussage in der Überschrift benennen, das Thema im ersten Satz wiederholen, Definitionen, Zahlen, Einheiten und Bedingungen in dem Satz belassen, der sie verwendet, Verweise auf „oben“ und „unten“ vermeiden, die Zusammenfassung zu einem eigenständigen Überblick machen und jeden Abschnitt testen, indem er in einem leeren Kontext gelesen wird.
Maschinenlesbar: JSON