Documentation and Knowledge Base

Guidelines for documentation of support and maintenance
Software documentation is any documentation produced to describe various aspects about a particular software system This makes the life of all the members associated with the software easier. It may contain anything from requirements documentation, design documentation, Testing documentation , API documentation, build notes, user manuals or help content. Documentation is a very critical process in software development and maintenance. Poorly documented systems can make it difficult to understand how the system works, making it difficult to carry out activities such as training users, transfer knowledge to new technical teams or to identify and fix problems. 

 As part of software maintenance, it is important to ensure that software documentation is updated to reflect any changes to software.  Documentation that may need to be updated as a result of changes to software includes user manuals, software technical documentation, user manuals and training materials. 

 Here are some examples of technical software product documentation that should be kept updated: 

 

 Product requirements document 

 Product design document 

 Technical architecture documentation 

 Test documentation 

 Source code documentation 

 Product roadmap 

 

 Here are some examples of user product documentation that should be kept updated: 

 

 Quick start guide 

 User manual 

 Installation manual 

 FAQs and troubleshooting tips

Knowledge base creation
A software knowledge base is a repository or library of information about a software product. Users can consult knowledge base texts to answer their questions and clear up ambiguities regarding the software. The documents in a knowledge base address the users’ frequently asked questions and provide solutions to the most common issues. 

 They focus on problem-solving, often incorporating workarounds or troubleshooting options. Therefore, a knowledge base is often used as a self-service portal. Users can browse self-help articles instead of contacting Customer Support. It is therefore important as part of software maintenance to ensure that any knowledge bases are updated as part of maintenance activities. For example maintaining a log of issues noted and how they have been resolved. 

 To make maintenance of software easier it is important to keep updated documentation of the following: 

 

 Configuration document - Configuration management documentation is primarily concerned with the functional relationships among parts, subsystems, and systems for controlling system change. It supports verifying that proposed changes are systematically analyzed to minimize adverse effects. 

 Documentation of common issues and their workarounds or resolutions. It is important to keep a record of common known issues and their workrounds and resolutions. This fast tracks 

Accessibility and availability of documentation for authorized personnel
Accessible documents benefit all authorized persons by making information clear, direct, easy to understand, and most importantly, usable by a wide audience, including people with disabilities and those who use a variety of devices, software and hardware. 

 To improve accessibility and availability of documentation , the following should be considered: 

 

 Have a common repository of documentation in the organization where relevant and authorised staff can easily access it . Staff should be informed of such repositories on a regular basis 

 Keep the documentation updated to ensure it remains relevant. 

 To improve accessibility especially to those with disabilities see RISA Software Accessibility guidelines