There are two types of documentation that should be produced when creating a new system:
  • User documentation
  • Technical documentation

Testing

stacks_image_E10DD35F-B52B-478D-8281-0C52F76AD967

Documentation

stacks_image_DF3B0575-CE87-456C-B11D-185D002A0A18

Implementation

User Documentation

The user documentation is intended to help the users of the system.

The users are usually non-technical people, who don't need to know how the system works. They just need to know how to use it.

User documentation usually includes:
  • List of minimum hardware and software required to use the system
  • How to install the system
  • How to start / stop the system
  • How to use the features of the system
  • Screenshots showing the system in typical use
  • Example inputs and outputs
  • Explanations of any error messages that might be shown
  • A troubleshooting guide
stacks_image_6F02DBA2-D752-43FD-84BA-D16E1625F9EE
If you've ever purchased any computer software (e.g. a game), then you will have seen a user guide - it's the little booklet that comes in the CD case (that you didn't read!)

If you buy a car, it comes with a user guide that explains how to start it, unlock the doors, fill it with fuel, etc. (nobody reads those either!)

Technical Documentation

The technical documentation is intended to help the maintainers of the system (the people who need to keep the system running smoothly, fix problems, etc.)

The maintainers are usually technical people, who need to know exactly how the system works.

Technical documentation usually includes:
  • Details of the hardware and software required for the system
  • Details of data structures (data types, field names, etc.)
  • Details of expected inputs
  • Details of validation checks
  • Details of how data is processed
  • Diagrams showing how data moves through the system
  • Flowcharts describing how the system works
stacks_image_A7086917-6968-4BF6-A578-89412F228C89
If you buy a car, you wouldn't normally want the technical documentation for it.

Your mechanic would be the person who would need the technical documents. If the car needed servicing, or fixing, the mechanic would look in the document to understood how the various systems in the car worked.