On this page
A useful workflow document lets a trained person handle a normal case, recognize an exception, locate the right record, make only authorized decisions, communicate status, recover from failure, and prove completion. A happy-path diagram alone cannot do that.
Start with trigger and accepted outcome
Name who or what starts the workflow, the conditions required to begin, the customer or operational outcome, and the evidence that closes it. Define the unit of work: request, order, call, document, incident, or account. This prevents a broad process map from hiding multiple distinct jobs.
For an illustrative account-change workflow, the trigger might be a verified request from an authorized contact. The accepted outcome is the approved change recorded in the system and accurately communicated. “Email sent” is not enough if the underlying update failed.
GOV.UK's user-needs guidance emphasizes what people need to accomplish. Apply that idea to the operator and recipient: both should be able to tell whether the workflow delivered its intended result.
State prerequisites beside the trigger. Missing identity evidence, required approval, or an unavailable system should lead to an explicit waiting or escalation state.
Capture the operating layers
- Actors, roles, authority, handoffs, and backup owners
- Records, fields, source systems, identifiers, and states
- Decision rules, prerequisites, approvals, and confirmation
- Normal steps, waits, service targets, notifications, and queues
- Exceptions, retries, rejection, cancellation, reversal, and outage
- Privacy, security, accessibility, retention, audit, and change control
Give each material state a meaning. “Pending” might mean waiting for the customer, another department, or a scheduled event. If those situations require different follow-up, distinguish them in the instructions.
Describe the record used to connect steps. A request identifier, order number, or case link helps the next person find the right context. Do not rely on a colleague remembering which email thread began the work.
Where authority ends, link to the customer-service escalation matrix. A procedure should tell an operator when to stop and transfer responsibility rather than encouraging an improvised exception.
Include cancellation and partial completion. If the requested change becomes unnecessary after approval but before execution, identify who can stop it and how that decision reaches the operator. If one system updates and another fails, the document should identify the current state and recovery owner rather than directing the person to restart blindly and risk a duplicate action.
Use the right artifact
| Artifact | Best use | Missing alone |
|---|---|---|
| Flowchart | Sequence and branches | Detailed rules and field meaning |
| Procedure | Step execution and evidence | Cross-team overview |
| Decision table | Complex combinations of conditions | Full sequence and ownership |
Keep the overview short enough to navigate, then link to detailed rules at the point they are needed. A flowchart can show where approval occurs; a decision table can explain which approval applies. Copying the same rule into several diagrams creates competing versions.
The Home Office documentation guidance focuses on reader needs and understandable structure. Use verbs that describe actions, name the relevant interface or record, and explain unfamiliar terms where they first matter.
Screenshots can help people find a control, but the text should explain what the action accomplishes. Otherwise a cosmetic interface change can make a still-valid rule appear obsolete.
Build documentation from observed work
- Interview the people doing and receiving the work.
- Trace recent normal and failed cases.
- Draft states, decisions, and responsibility.
- Validate against systems and policy owners.
- Run a tabletop case using only the document.
- Publish ownership, version, effective date, and feedback route.
Ask a trained colleague who did not draft the guide to complete a representative case using it. Observe where they pause, infer a missing rule, or ask someone for undocumented knowledge.
Then try an exception: a duplicate request, a rejected approval, or a partially completed update. These cases reveal whether the guide describes state and recovery or merely a sequence of clicks.
Record discrepancies between actual practice and approved policy. Do not silently document an unauthorized shortcut as the new standard. Give the relevant owner the evidence needed to decide whether practice or policy should change.
Avoid documentation that lies by omission
- Writing the intended process without observing the actual one
- Using role names that do not match permissions
- Leaving manual spreadsheets or inboxes outside the map
- Updating a screenshot while the rule beneath it changes
Do not automate an unresolved exception
If authority, policy, ownership, or desired outcome is disputed, document the decision gap and resolve it before encoding behavior into software.
Maintain the workflow as a controlled product
Track owner, version, effective date, review trigger, systems, policy references, training audience, known exceptions, and change log. Use incidents, repeat work, delay, and support questions to identify where the document or workflow needs revision. Archive superseded versions for traceability.
Use changes in systems, permissions, service promises, or recurring errors as review triggers. A calendar review alone may leave an important change undocumented for months.
Give readers a simple way to report a specific defect, such as a missing condition or inaccessible record. Route that feedback to the document owner and verify the corrected step with a relevant case.
Keep superseded material distinguishable from current instructions. Historical versions can explain an earlier decision, but search results and shared links should direct active operators to the authorized version they need today.
Continue with the next decision
Evaluate the workflow for automation. The complete map exposes where rules are stable and exceptions remain human.
Convert approved explanations into governed knowledge. Operational procedures and public answers require different access and scope.
Practical finish line
A trained operator can complete, escalate, reverse, and evidence the workflow from current documentation, and every material rule has an accountable owner and change history.
Sources and further reading
Primary and contextual sources used to verify definitions or give readers a relevant next resource.
- Home Office: Write Effective Documentation Documentation should address its readers' needs and use clear, accessible structure and language.
- GOV.UK: Learning About Users and Their Needs Service design begins with what users need to accomplish, informed by research rather than unsupported assumptions.