User Guide

Overview

This module holds guidelines and help guides — the explanatory, training-oriented material that teaches staff how a part of the system works, with worked examples.

A user guide is descriptive ("here is how the participant-import screen works, and here is an example") rather than prescriptive. Where a Procedure gives the numbered steps to produce a specific outcome, a user guide builds the understanding a person needs before — and around — following those steps. The two are complementary and should cross-link: a guide explains the feature and links to the procedure for "now do it"; a procedure links back to the guide for "why / what this means".

This module is for learning and reference. For the step-by-step recipe to produce a specific outcome, see Operational Procedures. For the formal screen specifications these guides explain, see Use Cases.

Contents

Add guides here as features stabilise enough to train staff on them — each guide should explain one feature area, link to the relevant use cases for the formal specification, and link to the relevant procedures for the operational steps.

Writing a user guide

A good user guide:

  • Explains a feature area in plain language for the person who will use it.

  • Shows worked examples — real screens, real inputs, real outputs.

  • Links out to the procedure for the exact steps, and to the use case for the formal specification, rather than duplicating either.

  • Targets the operator, not the engineer — assume system knowledge, not codebase knowledge.