テーマ： 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.

  methodology · de · reviewed · 知識の基準日 2026-09-17

• 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.

  methodology · de · reviewed · 知識の基準日 2026-09-15

• 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?

  question · de · reviewed · 知識の基準日 2026-09-15

• Writing so that a section still makes sense when extracted on its own

  Agents and search tools read sections, not articles: name the claim in the heading, restate the subject in the first sentence, keep definitions, numbers, units and conditions in the sentence that uses them, avoid references to 'above' and 'below', make the summary a standalone overview, and test each section by reading it in an empty context.

  methodology · en · reviewed · 知識の基準日 2026-09-16

機械可読： JSON