User manuals


User manuals are on what a software does and how to use it. What follows are too many meetings, wordy emails, tiring video calls, and more confusing explanations. Key is to communicate effectively with illustrations and maybe some video recordings. Using recognisable templates with examples of the various uses of the software helps too.


What does someone have to do to get “this” and “that”, things the software is supposed to do for a user? The written communication varies from verbose to concise.

Acceptance test: Someone new to the project, not necessarily a developer, can use the code with help of the manual.


  • Lay out usage examples step-by-step

  • Include plenty of diagrams and illustrations

  • Usually contains:

    • minimum hardware and software requirements

    • installation/setup guide and instructions on how to start the system (possibly in the form of a quickstart)

    • description of main features

    • instructions on how to use the system

    • cautions and warnings

    • Troubleshooting steps with examples of the most common error messages

    • contact information in case undocumented questions arise

    • Do not repeat in the documentation what can be figured out from the tests or by setting a breakpoint, calling the method, and following the execution path.


User manuals can be created using a variety of tools. Each tool has its own advantages and disadvantages.