205. Procedures: writing the how

“Adjust the settings as needed” is a small sentence with a generous view of what the reader already knows. It leaves the choice, the effect and the stopping point to someone who came to the page to find them.

A procedure supplies that missing route. It establishes where the reader starts, what they do, what the application does in response, and how they recognize the result. The writing can be attentive without becoming chatty. Often its most companionable act is to answer the question just before the reader has to ask it.

Give the procedure a definite job

Name the result in the heading: “Export a proof as PDF” or “Select corresponding points in another master.” A reader should be able to decide whether the page serves their task before following it.

A feature name can be the right reference heading. A procedure usually needs the action that uses the feature. “Export settings” and “Export a proof as PDF” make different promises; choose the one the page actually fulfills.

Write a private finish line before drafting. What will be present, changed or known when the task is complete? This helps distinguish necessary steps from a tour of nearby controls.

Do not promise a duration, compatibility or quality outcome merely to make the heading more attractive. “Your first proof in five minutes” needs evidence for that claim. The result itself is usually a sufficient invitation.

Establish the starting state

State the conditions that the route depends on: selected objects, active mode, required permission, available input, product version or supported platform. Make each condition concrete enough to check.

A reader may have a document open but the wrong layer active. They may have the right application and a different command context. These are small differences on screen and large differences to the next instruction.

Put a condition before the action it governs. If it applies to the whole task, state it before the steps. If it arises only in a later branch, place it before that branch's decision.

Do not invent prerequisites to make the page seem thorough. “Understand vector graphics” is rarely an actionable starting state. Name the specific knowledge or setup that the task requires and provide a route to it where needed.

Put consequences before commitment

A warning must arrive while the reader can still choose. State the affected object, scope and supported consequence before a destructive or irreversible action.

For a fictional review app, the source packet says that Remove from queue removes selected items from the review queue while leaving their source files unchanged. It does not describe undo.

Remove from queue removes the selected items from this queue. Their source files remain unchanged. Select the intended items before choosing the command.

The scope is useful reassurance because the packet supplies it. An additional promise that the items can be restored would need another fact.

Keep essential conditions in the required path. A collapsible note, tooltip or link may carry background, but should not be the only place where the reader learns what they are about to lose or replace.

Choose a supported route

A procedure covers its stated task through a supported route. It need not list every possible input method or begin with every way to open the document.

Choose the route appropriate to the audience, starting state and platform. Link or explain alternatives when a meaningful difference makes them useful. A shortcut can supplement a menu route without forcing every step to become a catalogue of gestures.

A tutorial has a different emphasis: it guides learning through a bounded example, with chosen material and values. It may pause to explain a result or help the reader notice a relationship. A task procedure can assume the reader already wants the result, while still explaining what is needed to reach it.

Both forms need accurate starting conditions and a complete route. Neither benefits from an unexpected branch introduced after the reader has committed to the wrong path.

Make steps easy to leave and return to

Number actions when their order matters or when numbering helps a reader return after looking at the application. Two dependent actions can deserve numbers; a single action can be expressed in a sentence.

Keep each step a manageable unit of attention. Closely connected actions in one place may fit together. Split a step when the reader must remember several unrelated choices or return to the instructions midway through it.

Name location before action when the location is needed to find the control. Once the context is established, avoid repeating it mechanically. Continuity lets the following steps be shorter.

Use exact labels and appropriate interaction verbs. Describe the intended state of a checkbox or option rather than an ambiguous click. Distinguish a press from a held key and a sequence from simultaneous keys. The interface-actions guide gives the full conventions.

A numbered item should ask the reader to do something. A result can follow the action within that item; it does not need a number of its own unless the reader must actively inspect or verify it.

Tell the reader what changed

A useful result statement closes a gap in observation. It can confirm that a mode changed, the intended layer became active, a selection moved, or output appeared in the expected place.

For the documented FontLab example discussed in chapter 202, switching from a glyph layer with selected points or segments to a matching master layer recreates the corresponding selection. A procedure using that behavior must retain the matching-layer condition and identify the selection, rather than imply that drawing data was copied.

State a result when it helps the reader decide whether to continue. Do not add a ceremonial “success” sentence after every obvious action. Conversely, saving or exporting may need confirmation when completion is not otherwise clear. Pressing a command is evidence of an attempt, not always of the intended result.

Keep request acceptance, progress and completion distinct. A queued job cannot be described as finished merely because the next step in the draft needs a finished file.

Use values that teach a choice

An example value needs a purpose. A tutorial can supply a tested value for its sample material. A general procedure may instead need a starting criterion and a documented direction of change.

State units, ranges and relevant dependencies. If no universal value is known, do not manufacture one. Explain the supported relationship and what the reader should inspect.

“Adjust until it looks right” can be acceptable in an explicitly aesthetic exercise with explained criteria. It is insufficient when the task has an observable technical condition that the writer has omitted.

A comparison strip can show the visible effect of several values. Its caption should identify what changed and what remained constant. The numbers in a picture are examples, not automatically recommended settings for every file.

Put branches where the path changes

A platform difference in one gesture can live inside the step. A different starting mode may need a branch before several steps. Distinct outputs may need separate short procedures.

State the decision in the reader's terms and give the applicable route. Avoid nesting several exceptions inside one long numbered item.

For a fictional packet that supports PDF output for a review copy and PNG for a raster preview, a brief choice can precede the export steps. That packet does not establish either format as appropriate for every printer or downstream application. The branch must preserve the stated purpose.

Use a table for independently selectable alternatives. Keep the sequence of actions outside the table so readers do not have to assemble a procedure from several cells.

Place recovery beside the relevant failure

A local recovery note can keep someone from abandoning the task. It needs an observed symptom, a supported action and a way to recognize the result.

Do not turn a symptom into an unsupported diagnosis. An unavailable output file does not prove a permissions failure. A stopped progress indicator does not prove that restarting the application is safe.

If a known failure has a documented remedy, place the note near the step where it can occur. If investigation branches widely, link to troubleshooting while keeping any immediate warning or preservation step in the procedure.

Recovery should be calm and specific. Remove blame and jokes. Reassurance belongs only where the product state supports it. “The source file is unchanged” is helpful when established; otherwise it conceals the very uncertainty the reader needs to resolve.

Worked repair: export one review copy

This is a fictional application, with the following packet for its normal successful path:

• A saved project is open.
• File > Export opens an export dialog.
• The dialog has Format and Folder controls and an Export button.
• PDF is available for this review-copy task.
• Export includes only saved changes and leaves the project file unchanged.
• A completed export creates a PDF in the chosen folder and reports its path.
• No overwrite or failure behavior is supplied.

Weak draft:

Open the export feature, configure it as needed, and share your work.

Revised procedure:

Export a PDF review copy

Use a saved project. The export includes only saved changes.

1. Choose File > Export. The export dialog opens.
2. Set Format to PDF.
3. Use Folder to choose the destination.
4. Click Export. On completion, the application reports the PDF's path.
5. Check that the PDF is present at the reported path.

The project file remains unchanged.

The example ends at a verified output, not at sharing it: no sharing operation was supplied. It also does not say what happens if an existing file has the same name. A real procedure must resolve that condition when it affects the intended route. The supplied successful path is not evidence for unstated branches.

The revision's warmth comes from anticipation. The reader is told which changes are included, where the result appears and what happens to the project. No sentence needs to congratulate them for reaching the folder.

Make screenshots support the route

Use a screenshot to locate a control, show a state or demonstrate a spatial relationship. Keep the necessary names and actions in text. An image can be missing, too small, from a different theme, or unavailable to the reader's presentation method.

Crop for the image's job without removing the context needed to locate its subject. A caption can identify the relevant panel, selection or version. Alt text should convey the information the image contributes in context.

If the surrounding text already provides all useful information, follow the publishing system's decorative-image convention rather than repeating an inventory of the screen. When the picture demonstrates a comparison, supply that comparison in its text alternative.

Inspect the rendered result. A clear source image can become illegible after scaling, and a correct caption can end up separated from the image it explains. A screenshot is a record of one state, not proof of every state the procedure claims to support.

Treat executable samples as procedures

Code has starting conditions, actions, consequences and postconditions too. Put runtime requirements and warnings before the block. Use documented names and identify placeholders before the reader copies them.

A real sample should be tested in its supported environment with representative input. Check the actual result, not just a printed success message or the absence of an exception. For a mutation, check relevant failure cases and protect the original through a supported route.

When the API has not been verified, use clearly identified pseudocode instead of plausible executable syntax. For example, this is pseudocode for a fictional rename task, not FontLab API code:

Open a working copy.
Find the source object by its exact name.
If the destination name is already in use, stop without renaming.
Rename through the documented operation.
Read the names again and confirm the intended change.
Review the result before saving the working copy.

The sequence teaches collision checking and verification without inventing an API. It cannot be labelled a runnable example until the actual operations, runtime and outcomes are established.

Link at the point where depth becomes useful

Keep facts needed to finish the current task in the procedure. Link to a concept when a relationship needs further explanation, to reference when the reader needs other values or modes, and to troubleshooting when the route departs from the expected state.

A required limitation should not live only at the destination. A brief reason can remain beside a step even when the fuller explanation has its own page.

Stop when the task reaches its stated result and necessary verification. A related task can be offered as a next route. It need not become another six steps appended to the current one.

Test from the stated conditions

Use the page with only the assumptions it gives the reader. Begin with safe sample material and the relevant product version, platform, settings and permissions. Defaults and remembered selections deserve particular attention: yesterday's state can make today's incomplete instructions appear to work.

Record expected and observed states at meaningful points. If persistence matters, check the relevant reopening or restart. If platform shortcuts are included, verify those assignments in their contexts. Test the failure routes claimed, or report that they remain unchecked.

A successful run on one machine is evidence for that run. It is useful when its scope is recorded. It becomes misleading only when reported as proof of unexamined environments or branches.

Separate product defects, documentation omissions and ambiguous source material. Repair the page where possible; preserve an unresolved gap rather than writing an imaginary route around it.

Practice: preserve the route while improving the prose

Use the fictional PDF packet. First write the steps in the order of action. Then write a short introduction that explains why saved changes and exported output are different things. Give the explanation a connected rhythm while keeping the steps literal. For example: “The project is the editable work; the PDF is the review copy made from its saved changes. Saving determines which changes that copy can contain.” This paragraph explains the relationship without adding a new action to the numbered route.

In the second pass, remove the fact that the project file remains unchanged. Revise every reassurance that depended on it. Next remove the reported-path confirmation. The procedure must now stop promising that signal and identify what verification evidence is missing.

Finally, add this supplied condition: an existing destination file triggers a Replace file confirmation. The packet does not yet state cancellation or replacement behavior. Put the decision at the right point and mark the remaining gaps; do not complete them from familiarity with another application.

Checklist

• The heading and finish line describe the same bounded task.
• Starting conditions are concrete and appear before dependent actions.
• Consequences arrive before commitment.
• Steps form a supported route with manageable units of attention.
• Labels, values, units and gestures retain their exact meaning.
• Results distinguish attempted, accepted and completed operations.
• Branches and recovery use supplied behavior without invented diagnoses.
• Images support instructions that remain available in text.
• Executable code is verified; pseudocode is identified before the block.
• Links offer depth without hiding required facts.
• Verification records the actual environment, observations and limits.