Program Documentation: Write a Guide a Reader Can Check

Write instructions that a new reader can follow

A useful user guide says what to do, what should appear and what to do when the expected result does not appear. “Enter the details and continue” leaves too much unstated. Name the control, describe an accepted entry and show a result the reader can compare with their own.

Here you will document Label Preview 1.0, an original fictional paper-model application. There is no downloadable program, live interface or screenshot. All behaviour is defined below, so the walkthroughs can be checked on paper. The labels describe objects and contain no personal records.

Know the reader and the version

The intended reader wants to prepare a numbered preview such as BOX-01, BOX-02 and BOX-03. They need input rules, actions, outcomes and correction instructions. They do not need variable names, loop internals or a database design. Developer notes explain implementation; this guide explains use.

The version matters because a later model might accept different prefixes, provide printing or change an error message. Instructions should describe the specified version rather than features that seem likely. The limited count range keeps the paper preview short enough to inspect completely.

A complete first-use guide

1. Begin with the Label Preview 1.0 paper model in its starting state. Confirm that Prefix and Count are blank, the preview contains no labels and status says “Ready”.
2. Choose BOX in Prefix. Expect Prefix to show BOX, Count to remain blank and the preview to remain empty. Status stays “Ready”.
3. Enter 3 in Count. Expect Count to show 3 and Prefix to remain BOX. Labels do not appear merely because a number was entered.
4. Select Preview. Expect status “Preview ready: 3 labels.” and the three lines BOX-01, BOX-02, BOX-03.
5. Compare all three lines with the intended batch. Check the prefix, numbering from 01, final number 03 and total of three labels. This is a preview only.
6. To start again, select Reset. Expect blank inputs, no preview labels and status “Ready”. Reset does not print or save anything.

The guide includes a starting condition because a reader who begins with an old preview could otherwise mistake it for the new result. It also distinguishes editing from Preview: changing an input alone cannot establish that the requested labels were generated.

Worked walkthrough 1: a valid small batch

Start ready, choose KIT and enter 2. Selecting Preview gives “Preview ready: 2 labels.” with KIT-01 and KIT-02. Compare these with the request for two KIT labels. The first line is not KIT-00, and the second line does not use a different prefix.

A weak instruction says “Check that it worked”. Replace it with “Confirm two lines: KIT-01 and KIT-02, and status ‘Preview ready: 2 labels.’” The replacement makes the success condition observable without explaining how a programmer builds the strings.

Worked walkthrough 2: correct a count without inventing conversion

Choose TAG and enter 2.5. On Preview, no labels appear. Status is “Enter a whole number from 1 to 20 without spaces, signs or leading zeros.” The fields remain TAG and 2.5, so the reader can see what needs correcting.

Replace the entire Count entry with 3. Editing clears any earlier result and returns status to “Ready”. Select Preview again. The expected lines are TAG-01, TAG-02 and TAG-03; status is “Preview ready: 3 labels.”

Do not tell the reader that the model rounds 2.5 or ignores punctuation. Neither behaviour is specified. The correction must use a newly chosen accepted count. Similarly, 03 and 3.0 are invalid entries in this model even though someone might interpret them as the number three elsewhere.

Worked walkthrough 3: avoid a stale preview

Begin with a successful BOX count of 3. Change Prefix to KIT. The model keeps Count at 3 but immediately clears the BOX preview and shows “Ready”. It does not instantly create KIT labels.

Now select Preview. The replacement result is KIT-01, KIT-02 and KIT-03 with “Preview ready: 3 labels.” The guide must include that second Preview action. An instruction that says “Change the prefix and use the labels below” would be wrong because the specified editing behaviour leaves the preview empty.

If both fields are invalid, the prefix message appears first. Correcting the prefix may then reveal the count message at the next Preview. Explain the order as expected behaviour rather than claiming the first correction guarantees success.

Keep a quick reference beside the full guide

A quick reference helps a returning reader find the next action. It does not replace the complete input contract or first-use example. Keep its action names and messages consistent with the longer guide; introducing an imaginary “Generate” button would make both harder to follow.

Check documentation against the model

Read each instruction literally and record its expected visible state. Ask whether the instruction names a real control in this specification, whether a first-time reader knows the accepted input, and whether the result follows from the stated action. Check corrections as carefully as success paths.

This is a fidelity review of instructions against predetermined behaviour. It does not establish that an actual application has been built or tested. If the specification changes, update the walkthroughs, messages and quick reference together. Until then, keep the version label visible and avoid promising unsupported printing, exporting or saved history.

Three solved practice tasks

Task 1: repair a misleading instruction

A draft says “Enter 04 for four labels.” Is it correct? Solution: no. Leading zeros are not accepted. Replace it with “Enter 4, then select Preview.” With prefix BOX, expect BOX-01 through BOX-04 and status “Preview ready: 4 labels.”

Task 2: explain the first correction

Prefix is CRATE and Count is 0. What happens on Preview? Solution: no labels appear and the prefix message is shown first. Choose an allowed prefix; Preview will then show the count message until the count is corrected to an accepted entry.

Task 3: check a two-digit endpoint

Choose KIT and enter 12. What should a guide tell the reader to inspect? Solution: twelve consecutive lines from KIT-01 to KIT-12, with no missing or repeated number, and status “Preview ready: 12 labels.” Two digits are used throughout, including 10, 11 and 12.

Further reading

Technical background: Write the Docs — writing software documentation. Examples, questions and diagrams in this lesson are original.