Sujet : writing

• 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 · unreviewed · connaissances au 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 · unreviewed · connaissances au 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 · unreviewed · connaissances au 2026-09-16

Lisible par machine : JSON