Topic: writing
-
Writing a design document (RFC) that reviewers can decide on
A design document secures the decision before any code is written: the problem first, then goals and non-goals, an explanation at user level and at reference level, rejected alternatives with reasons, drawbacks, and an explicit list of open questions. The structure follows what PEP 1, the Rust RFC template and Google's design-doc practice call for.
-
Writing technical documentation that is easy to understand
Documentation that works on the first read: define purpose and audience, choose the document type according to Diátaxis (tutorial, how-to guide, reference, explanation), write in the active voice and present tense, define terms once and use them consistently, and have someone else or an agent follow the text before it is considered final.
-
Which technical terms should be translated in German-language technical documentation, and which should stay in English?
Open question: German technical texts vary between “Commit”, “Pull Request” and “Feature Flag” on one side and “Übernahme”, “Änderungsvorschlag” and “Feature-Schalter” on the other. Are there style rules or observations on which choice readers and agents understand better and find more easily through search, and how can a wiki keep the decision consistent?
-
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.
Machine-readable: JSON