201. Volume II: technical writing and product documentation

The reader can see the setting. The missing piece is why changing it would help. A technical explanation closes that distance: it connects the visible control, the behavior behind it and the result the reader can recognize. An instruction then gives the supported route to that result.

This volume follows that work from voice and terminology through concepts, procedures, reference, release notes and help architecture. The prose can be patient, observant and occasionally dry. Its personality should make a difficult relationship easier to follow; it must not supply a capability the product lacks.

The operational guide owns the current house rules. The glossary owns agreed terminology and distinguishes it from proposals. These chapters develop the judgment behind those decisions.

Choose the chapter for the reader's question

202. The house voice

Make responsibility visible: what the reader chooses, what the application does, and what the resulting data contains. Develop the explanation through concrete observations and connected sentences. Keep conditions, uncertainty and the actual event intact when the tone changes.

203. Terminology: calling things by their names

Separate an exact interface label from the concept it names and the words a reader uses to search for it. Explain the unfamiliar term without changing the control, identifier or product distinction. Repetition is useful when a synonym would quietly introduce a second object.

204. Explaining concepts

Begin with a useful distinction or an observable puzzle. Explain the mechanism, then choose a comparison or example that helps the reader see it. An analogy has a job and a boundary; it need not become a complete alternative universe.

205. Procedures: writing the how

Establish the goal and starting state, order the supported actions, and show how to recognize the result. Put consequential conditions before the action. Keep an illustrative sequence distinct from a procedure someone can actually run.

206. Reference: pages people land on

Give a direct arrival enough context to identify the term or setting. Make values, units, defaults, effects and limits easy to compare. The reader came for an answer and may have skipped every introduction you carefully wrote.

207. What's new: release notes people read

Explain the change, affected work and required action at the scale each deserves. A fix needs its trigger and corrected behavior; a larger change may need a mechanism and a limit. Preserve the release's historical meaning.

208. Architecture of help

Connect explanations, tasks, reference and recovery into routes readers can find. Titles, search terms and links should agree about the destination. Support a first visit and a return to one small, forgotten fact.

209. Accuracy and the editing pass

Compare claims with applicable evidence, inspect the finished route, and review the prose for both clarity and character. A clean build establishes one kind of success. A supported explanation and usable procedure require their own checks.

Work through one passage twice

For the first pass, choose a bounded task and gather its facts. Write an explanation that lets the reader picture a relevant object and follow what happens to it. Let sentence length follow the movement of the thought.

For the second, mark every action, condition and result. Compare each with the source. Then inspect the expressive choices: does the detail clarify, does the analogy stay within its relation, and does the final sentence advance the point? Keep the useful character while repairing any unsupported claim. A successful second pass need not make the passage plainer: it can replace a vague flourish with a more revealing detail that the source actually supports.

Try a harder version by removing one fact from the packet. Revise the passage again. If its attractive ending still depends on the missing fact, the ending needs work too.