Authoring a User Guide Module

A user guide teaches a staff member or end-user how a feature works, with worked examples. It is descriptive — explanation and illustration — rather than prescriptive. Where a procedure gives the numbered steps to produce an outcome, a user guide builds the understanding a person needs before and around following those steps.

1. When to use this type

Create a User Guide module when there are non-engineer users who must learn the system, and the features are stable enough to train on. If your only audience is engineers, you almost certainly do not need this type — skip it (see choosing types).

It IS a user guide when… It is NOT a user guide when…

It explains a feature and shows examples

It prescribes steps to an outcome → Procedures

The reader is learning, not executing a known task

The reader is an engineer → Design / Operations

It targets the operator/end-user

It is the formal screen spec → a Use Case

2. Standard structure

modules/user-guide/
├── nav.adoc
├── images/                       # Screenshots are first-class here
└── pages/
    ├── index.adoc                # What the system does + where to start
    ├── <feature-area>.adoc       # One guide per feature area
    └── <getting-started>.adoc    # Orientation for a brand-new user

Screenshots and worked examples carry the weight in this module — budget for an images/ directory and keep captures current.

3. Page template

A user guide explains, shows, and links out. Copy templates/user-guide-template.adoc, or:

= <Feature area>
:description: <one line — what this teaches and to whom>

== What it's for
<Plain-language explanation of the feature and when a user reaches for it.>

== How it works
<The concepts and screen elements, in the user's language — with screenshots.>

== Worked example
<A real, end-to-end example: real inputs, real screens, real outputs.>

== Tips & gotchas
<Common confusions, and what the UI is telling the user when it disables/limits something.>

== Do it
<Link to the procedure for the exact steps; link to the use case for the formal spec.>

Explain, don’t duplicate. Link to the procedure for the exact steps and to the formal use case for the specification. The user guide’s job is understanding and examples, not the canonical step list.

4. Flexibility

  • No external users: omit this type entirely.

  • Few features: a single page per feature area; add a getting-started orientation once there is more than one.

  • Rich UI: invest in screenshots and worked examples; consider a short concept page that several feature guides reference.

5. Quality checklist

  • Targets the operator/end-user in their language, not the engineer.

  • Includes at least one worked example with real inputs and outputs.

  • Screenshots are current and legible.

  • Links out to the procedure (steps) and use case (spec) rather than restating them.

  • Explains disabled/limited affordances rather than leaving the user guessing.

6. Common pitfalls

  • Becoming a procedure — if it’s a numbered recipe to an outcome, it belongs in Procedures.

  • Stale screenshots — nothing erodes trust faster; date or version-tag the captures.

  • Engineer’s voice — assume system knowledge, not codebase knowledge.

  • Created prematurely — a user guide for an unstable feature will be wrong by next sprint.

7. Related