Writing well
Use for factual nonfiction, technical explanations, and instructions. Clear wording also supports stories. Their narrative structure comes from storytelling.
Sources and scope
William Zinsser's On Writing Well covers nonfiction, including science and technology. In Visions and Revisions, Zinsser describes the book's focus on clear, simple, concise writing, voice, and removing clutter. His Writing English as a Second Language also connects plain language with a writer's humanity.
These sources support the language principles. The procedure rules below are our adaptation to technical documentation. They do not imply that Zinsser limits his advice to technical writing or rejects storytelling.
Explain directly
- Clarify the thought first. Identify the fact to understand or the task to complete before editing sentences.
- Remove clutter. Cut words that add no meaning. Keep necessary conditions, exceptions, units, and uncertainty.
- Use familiar words. Name the actor and action. Define necessary technical terms before relying on them.
- Keep a human voice. Preserve the author's clear phrasing. Warmth does not require anecdotes or decorative language.
- Revise for the reader. Check that each sentence follows from the previous one and answers the next useful question.
Apply to technical detail
State prerequisites before actions. Put a condition before the instruction it controls. Give commands a working directory and explain the expected result. Use numbered steps when order matters. Use headings for tasks and tables for comparable options. Keep one meaning for each technical term. Preserve exact commands, identifiers, and API names. Simplify the explanation without simplifying away behavior the reader needs.
Never delay a required fact to create suspense. Never require a reader to finish a story before finding a command. Keep origin stories in their own section. Keep technical explanations complete when read on their own. If a factual example helps, place it beside the behavior it explains and distinguish illustration from measured evidence.
Before delivery, compare technical claims with inspected evidence and follow the steps in order. Report unavailable checks. Plain wording cannot make an unsupported command correct.