Define the writing assignment · Lesson 4

Select document form and done criteria

4 min read

Lesson objectives

  • Choose a documentation type and define done criteria.
Reading tools

Calling an artifact a “guide” does not tell a writer what readers need. A requester may ask for one page containing a first-use sequence, a field list, the reason for an administrative choice, and error remedies. Those are different information forms. Before choosing an output, identify the reading decision: does the reader need to act in order, look up a value, understand a cause, or recover from a failure? A procedure directs sequential action; a reference supports lookup; an explanation connects concepts and reasons; troubleshooting starts with an observed symptom and leads to a safe test, remedy, or escalation. The forms can make a connected set, but merging them into one paragraph hides the entry point.

Map required content to document form. First-time account registration calls for a short procedure with prerequisites, actions, and expected results. Many field definitions may belong in a linked reference table rather than being repeated in each step. Different permissions may warrant a conceptual page about roles before the procedure, without forcing experienced readers to reread it on every visit. Literary polish alone cannot choose the form. Attractive prose that mixes “do this now” with historical context can slow a task or conceal a condition that matters.

Write a definition of done for each piece. For a procedure, the reader knows prerequisites, completes the sequence on the relevant release, and recognizes the result or error path. For a reference, a reader finds a field value and conditions without conflicting interpretations. For an explanation, the reader distinguishes where a concept applies from where it does not. For troubleshooting, the reader starts from a specified message or symptom, checks a possible cause safely, then stops or escalates if the branch does not fit. These are reviewable checks, not invented success rates. Add source-version, language, and accessibility checks suited to the artifact.

Keep the task’s size in view. A compact getting-started page may link to detailed reference pages, but links should describe their destinations rather than promise generic “more.” Do not split every small condition into a separate file; excessive navigation can force the reader to remember too much context. Keep what is needed for safe action on the task page and move occasional lookup facts to a clearly labeled reference. Choose the structure by walking a reader path: from the starting point, can the reader reach the action and result without guessing where an essential fact lives?

State what the set does not supply. A getting-started page cannot replace an official eligibility policy. An error description does not grant the writer authority to alter records. A fictional example does not establish behavior of an actual product. Put unresolved release decisions on a hold list. The handoff then has defined forms, links between them, acceptance checks for each, and a visible boundary around what cannot yet be claimed.

Lesson summary

Choose a documentation type and define done criteria.