202. The house voice

A selection has disappeared. The reader needs to know whether the drawing changed, whether only the selection changed, or whether another layer is now in view. “Seamless editing” offers remarkably little assistance with these questions.

The technical house voice pays attention to the thing the reader can inspect. It names the action, explains the response, and keeps the condition that makes the explanation true. It can also make a complicated relationship pleasant to follow. Precision and a companionable voice have plenty to say to each other.

The current rules live in the operational guide. This chapter shows how to turn them into sentences with a visible subject, a useful movement and an honest stopping point.

Know who does what

Distinguish the reader's action, the application's response and the data that carries the result. A file can contain instructions or values that another program interprets. Describing the file as making a decision can hide where the decision actually occurs.

For font documentation, that distinction matters whenever the editor stores information and another application applies it. Explain both parts when the reader needs to understand why an exported result differs between applications. Do not give the font responsibility for behavior that belongs to the software using it.

A named feature can be the subject when its behavior is the subject of the explanation. “The filter changes the selected objects” can be accurate within a supplied product model. “The workflow understands your intentions” supplies judgment that a workflow description has not established.

Underline the subject and verb in a doubtful sentence. Ask what performs that operation in the actual model. An active sentence can assign the work to the wrong thing; a passive can accurately describe a result when the actor is unknown or unimportant to the reader.

Follow an action into its result

FontLab 8's release documentation provides a useful example: select points or segments in a glyph layer, then switch to a matching master layer. FontLab recreates the corresponding selection there.

The condition matching matters. The selected objects matter. The result is a corresponding selection, not a copied drawing. A smoother sentence that loses one of those distinctions teaches a different operation.

An explanatory version can make the boundary explicit:

With points or segments selected in one glyph layer, switch to a matching master layer. FontLab recreates the corresponding selection in that layer.

This is an example from that documented release behavior, not a claim that the workflow has been tested here in every version. Product instructions still need evidence for their intended version and environment.

The general pattern is useful: starting condition, action, response. Vary its arrangement according to the reader's question. Someone looking up a response may need the response first; someone following a procedure needs the condition before acting. The pattern serves the explanation without dictating every sentence's word order.

Keep conditions attached to their consequences

A condition can govern one action, several steps, or an entire section. Put it where that scope is clear.

For this fictional editor:

• The preview updates only when the document is open and Live preview is on.
• Changing the spacing then updates the preview.
• No saved-file behavior is supplied.

A compact explanation is:

With the document open and Live preview on, changing the spacing updates the preview.

A longer task passage could put those two starting conditions before the steps. What it cannot do is drop the open-document condition or claim that the saved file changes too.

Preserve the logic when splitting a sentence. Both, either, unless and only are small words with large responsibilities. Two short sentences that separate a condition from its consequence can be less clear than one longer sentence that keeps the relationship intact.

When several conditions crowd an opening, use a setup paragraph or list, then state the action and response. Shortening the sentence is useful only if the reader still knows when it applies.

Let tense describe the event

Present tense normally describes current behavior. Past tense reports an observed failure or earlier state. Future tense belongs to a future event or commitment supported by the source.

“Export failed” tells the reader what happened. Replacing it with “Export fails” can turn a particular event into a general behavior. A preference for present tense must not make that change silently.

Use if for a condition and when for an expected event or timing relationship. Neither word establishes the duration of an effect. If the preview changes only while a key is held, say so. If the change persists after release, that is another fact to establish.

In release notes, identify the change and its scope. Added, changed, removed and now can all be useful. Keep the earlier behavior only when it is known, and preserve the historical account when later releases behave differently.

Put purpose where it helps the reader find the action

“To change the preview size…” can orient someone scanning a collection of independent operations. In an already titled procedure, each step may begin directly with its action. Repeating the full purpose before every small action can make the reader wait through an introduction they have already accepted.

Name the control the reader needs and the effect the source supports. Do not replace an exact label with a friendlier invention. The surrounding sentence can explain what an awkward label means.

Ordinary instructions usually need no please. A request for information, repeated work or patience may call for explicit courtesy. The distinction is between helping someone perform their task and asking something of them, not between permitted and forbidden politeness.

Use we when the team owns an action or decision relevant to the reader. A company can state that it changed a policy or made a commitment. Keep self-congratulation from occupying the space where the consequence belongs.

Develop the explanation through a visible difference

An explanation becomes companionable when it notices the point where a reader might reasonably become uncertain.

In the fictional preview example, the preview can change while saved-file behavior remains unspecified. That distinction gives the paragraph a subject more useful than a claim about an efficient workflow:

The preview lets you inspect the changed spacing while the document is open and Live preview is on. It shows the effect of that adjustment. Whether the saved file has changed is a separate question this example does not answer.

The paragraph moves from condition to observation to limit. The short middle sentence lets the reader settle what is known before meeting the boundary.

A technical explanation can also begin with a puzzle: two views show different results, or one setting affects only part of the document. Resolve the puzzle through the actual mechanism. Do not delay a warning or required condition for the sake of a satisfying reveal.

Select the detail that explains the relationship. A slider's name or a visible change can be enough. An imaginary deadline and a customer's imagined relief would create a story the evidence did not supply.

Attach a benefit to its mechanism

A useful consequence answers why this behavior matters in the reader's task. It should be a supported consequence, not a standard phrase added to the end of every feature description.

For a fictional comparison view that places two supplied proofs side by side, “Compare the two proofs without switching between their separate views” follows from the stated arrangement. “Finish reviews twice as fast” needs a measurement. “Choose the better drawing automatically” requires a different capability.

Keep the mechanism and its boundary visible. A comparison view can help a person inspect differences without deciding which design is better. The distinction can itself provide a restrained closing observation:

The two proofs share a view. The judgment is still yours.

Use that line only when the source establishes the comparison and the human choice, as this fictional packet does. In a task step, the literal action may be all that is needed.

Do not require a benefit to be unique to one feature in the entire product. Several features may support the same real task. Require the particular mechanism to justify the consequence claimed here.

Make limits part of the explanation

A limitation belongs beside the capability it qualifies. A reader should not complete a long setup before discovering that their case is excluded.

State a known boundary plainly. Preserve uncertainty when the source is uncertain. May and usually are not weaknesses to remove by default; they may carry the distinction between possible and certain behavior.

If a condition is known, describe it. If the relevant behavior is not known, keep that gap in the working notes and obtain evidence before promising a complete answer. Replacing uncertainty with an absolute makes the prose more confident and the documentation less dependable.

A negative sentence can be the most useful sentence on the page. “Applying the preset does not start export” distinguishes preparation from execution in an example where that behavior is supplied. It needs no apology and no cheerful follow-up.

Vary rhythm without varying names

Exact terminology provides stable objects around which sentence rhythm can change. You can move a condition, develop an explanation, or shorten a conclusion without renaming the setting halfway through the paragraph.

Use parallel structure when readers compare alternatives. If several operations share a true rule, state the rule and identify the differences. Do not infer a universal modifier-key rule from a few examples: every combination still needs support from the product contract.

A table can make independent states easy to compare. A paragraph can explain why one state leads to another. Choose the form from that relationship.

Read a run of similar sentences aloud. Repetition may be useful in release notes where readers scan for a particular trigger. In an explanatory passage it may bury the developing thought. Change the shape where it helps the reader follow that thought, not merely to avoid repeating the product name.

Give warmth room where it helps

Warmth can come from patience, a well-chosen example or a small observation that recognizes the work. It does not require a theatrical announcement at the start of every tutorial.

An overview or concept explanation can use a harmless analogy or dry turn. Keep literal instructions easy to find and perform. Errors, uncertain loss, account access, licensing and consequential decisions need known facts and supported actions without jokes.

There is no useful count of warm sentences that makes a chapter safe. Read the actual situation. A first successful result may invite a brief acknowledgment; a result of uncertain status cannot borrow that confidence.

The same voice can move between surfaces without a lurch. Signal the change of job with a heading, a transition or a clearly separated procedure. A reference entry does not need to imitate an advertisement, and an explanation need not sound like a machine log throughout.

Repair the relationship, not just the wording

A revision should fix the observable problem while preserving the source.

Draft problem	First repair
An abstraction performs an unexplained action	Identify the person, application or mechanism that actually acts
A long opening stacks conditions	Group the setup while preserving its logic and scope
Several bullets repeat the same frame	Check for a supported common rule, then expose the actual differences
A benefit could mean almost anything	State the relevant consequence of the described mechanism
A joke appears during a failure	Remove it; report the known state and supported route
A recovery sentence offers reassurance without evidence	Preserve the uncertainty and obtain the missing state information
Every sentence has the same emphatic rhythm	Develop the connection and reserve emphasis for a real turn

A failed export joke cannot be repaired by inventing where the output was saved. A vague claim about easier work cannot be repaired by adding a precise shortcut that nobody checked. The first job is to establish the relationship. Then write it well.

Practice: one behavior, three surfaces

Use this fictional packet:

• The Compare command opens two selected proofs in one comparison view.
• It requires exactly two proofs to be selected.
• The view does not choose a preferred proof.
• No keyboard shortcut or time saving is supplied.

Procedure

Select exactly two proofs, then choose Compare. The comparison view opens.

Concept explanation

Select two proofs and Compare brings them into one view. Their differences can be inspected together; choosing a preferred proof remains a separate judgment.

Reference

Compare opens the two selected proofs in one view. The command requires exactly two selected proofs and does not choose a preferred proof.

The procedure gives a route, the explanation develops the relationship, and the reference states the contract. None adds a shortcut or measured saving.

For a second pass, remove the requirement for exactly two selections. Keep the supplied behavior about two selected proofs, but stop asserting that every other selection count is rejected. Then vary the explanatory paragraph's rhythm while preserving that narrower claim.

Read the variants once without their labels. Identify which sentence explains a relationship and which tells the reader to act. If they differ only in decoration, revise the explanation until it develops the distinction the procedure relies on.

Checklist

• Subjects and verbs match the product's actual division of responsibility.
• Conditions retain their logic and remain attached to the relevant action.
• Tense, timing and duration describe the supported event.
• Exact names stay stable while sentence shape varies.
• Explanations develop through a relevant observation and relationship.
• Benefits follow from the mechanism without invented measurements.
• Limits and uncertainty remain visible.
• Warmth helps the reader's task and leaves consequential states plain.
• Revisions repair a named problem without adding a new factual claim.
• Worked variants preserve the same behavior at different levels of detail.