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

This module is new. 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.