What Is Documentation?
Definition
Documentation
All information collected during software development that involves the system. It helps people understand, use, and maintain the system
Why Do We Need Documentation?
- Facilitates User Adoption: Clear documentation helps users understand how to use the system, reducing resistance to change and guiding users on how to fully utilise the system's features, leading to higher satisfaction.
- Makes Maintenance Easier: Well-documented systems minimise the need for technical support by empowering users to solve problems independently.
- Supports Training and Onboarding: Documentation serves as a valuable resource for training new users and onboarding employees.
- Ensures Compliance and Safety: In industries with strict regulations, documentation ensures that users follow the correct procedures, thereby reducing the risk of errors.
Types of Documentation
There are two main types:
- Internal: System (Technical) Documentation
- External: User Documentation
| Documentation Type | Where to find? | How it is applied? | Purpose |
|---|---|---|---|
| Internal Documentation | Found within the source code | Includes comments, meaningful variable names, and code structure | Aids developers in understanding and maintaining the code |
| External Documentation | Separate from the code | Includes user manuals, installation guides, FAQs, and troubleshooting tips | Designed for end-users to interact effectively with the system |
Key aspects of how to write good and efficient user documentation can be described as:
- Clarity and Simplicity:
- Use straightforward language and avoid technical jargon.
- Break down complex tasks into simple, step-by-step instructions.
- Use the same terminology.
- Visual Aids:
- Include diagrams, screenshots, and flowcharts to illustrate processes.
- Organization:
- Structure the document logically, with clear headings and a table of contents.
- Availability:
- Ensure the documentation is always available, both online and offline.
- Relevance:
- Tailor the content to the specific needs of the user, including FAQs and troubleshooting sections.
- Regularly update documentation based on user feedback and system changes.
Methods of Providing User Documentation
Some examples of ways to provide user documentation that you might find helpful:
Printed Manuals:
- Advantages: Accessible without an internet connection.
- Disadvantages: Can become outdated quickly.
- Think of a printed manual as a cookbook.
- It provides detailed recipes(instructions), but if a new dish (feature) is added, the book can't be updated without reprinting.
Manual for a new kitchen appliance.
