1.1.8 – The importance of user documentation
As programs become more complex and detailed a users way of thinking may differ from the developers.
This may lead to serious problems during the implementation or operational stage of the Software Life Cycle (SLC).
The user might not know how to use the product to its full capacity, and even specialized technicians may not be able to set up the new system properly for the firm they work for.
This is where there is a need for an effective and detailed instruction manual highlighting all components of the program.
Internal documentation is the code comprehension features and details provided as part of the source code itself. Proper internal documentation includes:
- Appropriate module headers
- Appropriate comments – Yes!! All IB Students take note!
- Useful and meaningful variable names
- Useful module, classes, methods and function headers
- Appropriate code indentation
- Appropriate code structuring
- Appropriate use of data types defined by the user
This would be near impossible to understand by just looking at the source code
External documentation is typically written as a separate document from the program itself.
It is provided through various types of user supporting documents such as a users’ guides, software requirements specification, detailed description of the design and implementation features of the program and test document.
Examples of External Documentation
1.1.9 – Different methods of providing user documentation
The user documentation should include all the instructions that are mandatory for the system to operate and should contain frequently asked questions, which are always necessary for new users.
The document should be well structured and divided into the appropriate categories.
User documentation can either be in a printed or in an online medium
Whether it be a hard copy or something like a .pdf document
Email any issues and they can reply
Embedded Assistance or integrated user assistance
When you are working on something and a box pops up to give instructions or tips
Other Examples Include:
- Frequently Asked Questions – Usually a page where the most common questions are answered
- Live chat sessions- Acts like chat software and usually via text where the user and support can discuss the problem and a solution
- Online portals or web portals- These can contain updated manuals and a support forum where people can discuss and help each other u
- Remote Desktop Connections – Someone is able to log into your computer and solve the issue for you