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.
Context
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.
Guides
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.
Resources
User manuals can be created using a variety of tools. Each tool has its own advantages and disadvantages.