101. Volume I: writing about software

The reader has opened your page because something needs doing. Perhaps a proof needs exporting, perhaps a feature needs explaining, perhaps the export has just failed. The first writing decision is which of these conversations you have joined.

This volume follows the work from that decision to the finished page: choose the useful detail, put the action into words, develop a paragraph and test what it asks the reader to understand. The prose should have an attentive mind behind it. A precise observation and a sentence that knows where to end will do more than a coat of enthusiasm.

Use the operational guide for the current house rules. Read these chapters for the choices behind them. Examples teach a decision; fictional examples do not establish product behavior.

102. Know your reader

Find the question already in progress. Turn observed actions and questions into headings, explanations and recovery guidance. Practice changing the opening for a blocked reader, a learner and someone returning to a familiar task.

103. Words that work

Choose the actual event before choosing its verb. Use nouns the reader can recognize, keep the small words that carry conditions and give numbers their context. Practice making a sentence more direct without turning an available operation into a completed one.

104. Sentences and paragraphs

Give a thought enough room to develop, then let its consequence land. Use sentence length, punctuation and paragraph breaks to make relationships audible and visible. Keep the reader with you through the qualification.

105. Structure: writing for scanners

Make the answer easy to find and substantial enough to use. Choose headings, lists and tables for the relationships they express. Put prerequisites and warnings where they can still affect the reader's action.

106. Voice and tone

Carry the same care through a launch story and a failure message while changing the degree of expression. Let warmth come from useful attention. An unknown cause remains unknown even in the friendliest sentence.

107. Story: the oldest interface

Let an action alter the situation and give the next sentence a reason to exist. Use a scene when it explains a choice or a mechanism. Keep invented illustrations visibly distinct from documented events and executable tasks.

108. Humor: the unsignalled smile

Find the small discrepancy the facts already contain. Let the reader notice it. Check the literal meaning, the target of the joke and the cost of delaying the answer; sometimes the best comic edit is a deletion.

109. Process: draft, rest, cut

Draft with the sources at hand, return with fresh attention and cut what no longer earns its space. Read aloud, follow the task and record what you actually checked. Keep the detail that an overly smooth revision might erase.

Put the volume to work

Choose a real paragraph and state its reader's task. Rewrite it once for clarity and movement. Then compare every claim with its evidence and test the action or explanation it offers. Keep both versions long enough to see which decisions improved the result. A shorter page is useful only when the reader loses nothing they need.

Record a specific result: a delayed condition moved earlier, an abstract claim replaced by an observed detail, or a long sentence retained because it holds a necessary relationship together. Use those decisions when revising the next passage; avoid copying the previous passage's surface pattern.