technical-writing
Technical writing
Write technical prose a tired reader can understand on the first read. Own reader/document job, instruction structure, technical sentence clarity, and unambiguous syntax. Produce complete usable prose from this owner; do not require a second cleanup skill for normal completion.
Use the vocabulary of the thing being described. Prefer its established domain/project terms and exact identifiers—symbols, files, flags, commands, standards, labels, component names, or other authoritative terms—over invented synonyms.
Choose the reader job
Use the Diátaxis distinction when a document needs a clear information mode:
- Tutorial — learning by doing. Lead the learner through a concrete result and show expected outcomes.
- How-to — action for a competent reader. Give the shortest useful steps to a goal; move background elsewhere.
- Reference — facts for lookup. Mirror the structure of the thing described and avoid persuasion.
- Explanation — understanding and why. Explain context, constraints, alternatives, and decisions around one bounded topic.
Do not mix jobs merely to make one file complete. Split/link when the reader's purpose materially changes. Repository-facing messages, reports, specifications, and other technical artifacts need not be forced into Diátaxis when their native form is already clear.