Documentation plays a huge role in Waterfall project management, where all the planning is done before the development stages. Even in the Agile approach, being flexible doesn’t mean that you revoke all bureaucracy, and documentation in a project is obsolete. Used wisely and efficiently, documentation plays a very important role in every project.
What is Software Documentation?
Documentation in software engineering covers all written documents and materials dealing with a software product’s development and use.
Documentation exists to describe product functionality, collect project-related information, and allow for discussing all significant questions arising between stakeholders and developers. Also, from the testing and users’ perspective, it is a crucial part of the project.
Documentation also prevents any consequences that may arise from unexpected events indicated by the bus factor.
What’s Your Role in Project Documentation?
It is essential for you, as a stakeholder, to get involved in creating documents. It’s especially crucial at the beginning of the project while documenting requirements. With the agile approach, you cannot treat the initial demands as set-in-stone forever, so it’s important to monitor the situation and adjust them. Even though they may change during the development, they should be accurate enough to initiate a successful start of the project. The project documentation must serve its main purpose – ensure that developers and stakeholders are headed in the same direction to accomplish the objectives of the project, so you should go above and beyond to ensure successful communication.
Types of Project Documentation
Agile is the most common practice in software development, so we’ll focus on documentation practices related to this method.
All software documentation can be divided into two main categories:
- Product documentation,
- Process documentation.
Product documentation is focused on the product – it describes the product and shows the various tasks that need to be performed with it.
Process documentation is a crucial element of the communication between the development team and stakeholders. It describes the process of developing the product.
Product Documentation
System documentation and user documentation are the two types of product documentation. Both require the stakeholders’ engagement and attention.
System documentation consists of documents that describe the system and its parts.
Examples of system documentation:
Requirements documents
Requirements usually are mostly described in the Statement of work (SOW) document. It is good to give them a more comprehensive form within one web-page that can be accessed by all team members. Using tables and graphs to show business rules, user stories, use cases, etc. will make it clearer and more readable.
Embedding this document within used project management tools (like Microsoft Azure DevOps or Atlassian Confluence & Jira) makes it accessible to all current and future team members. It’s also advisable to link external information in such a document, so there’s no need to search for it in many different places.
Software architecture document
This document should include the most important information about the design and architecture, there’s no need to list everything in detail. Design template, architecture & design principles, User Story description, solutions details, and diagrams should be discussed with stakeholders and included in this document.
Source code document
Source code document is dedicated to software engineers. It is not necessary, but it is recommended to list the most confusing aspects. It can include information about frameworks applied (like HTML generation framework), type of data binding, design pattern with examples (e.g. model-view-controller), security measures, other crucial patterns and principles. It should be simple, and each element should be shortly described.
QA documentation
Testing is closely connected with the user experience and it requires cooperation with stakeholders. Engineers prepare test strategy, test plans, test cases (including edge cases), test checklist, and include them in this document. All these elements should be composed according to best practices and stakeholders’ input is invaluable, especially while analysing the edge cases.
Maintenance and help guides
This document includes dependencies between different parts of the system and the existing problems with their solutions.
User documentation consists of manuals mainly prepared for end-users of the product and system administrators. Tutorials and onboarding can take shape of an onboarding training, but one cannot escape writing comprehensive user guides. To help users navigate through instructions you should use different forms of displaying information. Getting through vast instruction manual can discourage anyone from using the system. FAQs section, video tutorials, embedded assistance, and support portals can solve this problem. You should choose the best form for your product.
Examples of user documentation:
Tutorials
They can be presented in a form of a document describing each step of the system configuration. Lately, it is better to invest in a video posted directly on product’s page or social media platforms.
User guides
User guides should not only describe systems’ functionalities but also be easy to navigate. It is essential that users can find information fast when they need it. Only a few people read the whole manual at one go, mostly users read it when they are forced by circumstances and must solve specific issues.
Troubleshooting manuals
While creating the product it’s advisable to identify any problems that may occur during the use. Gathering those problems and describing solutions enables users to deal with smaller issues on their own, especially when the support is currently not available.
Installation manuals
It is good to place installation manuals with the installation packages. It’s advisable to link them at the same web page, so users wouldn’t have to search for it.
Best practices:
The best products emerge from considering users’ feedback, thus using a form of documentation to enable collecting users’ comments is the best solution. The wiki system is clear and every documentation update is easy. It is a good idea to conduct a survey asking users whether a certain explanation in the instruction was useful and to allow them to send their comments.
Process Documentation
It consists of all documents produced during development and maintenance. It is available for the whole team and stakeholders, providing them with information about the process itself.
Examples of process documentation:
Project plans, estimates, and schedules
They are usually created before the project and can be changed as the product evolves.
Reports
They illustrate how time and human resources were used during the development process. Each report shows a moment in time that provides information for the next steps of the project and can influence changes in business decisions.
Standards
These documents consist of all coding and UX standards used by the team in the project.
Meeting notes
Notes taken during meetings provide useful insights on what should be included and implemented in the next stages of the project. They also collect a historical record of the communication in the project.
Best practices:
At the beginning of the project, it is good to agree with the team and stakeholders on the list of process documentation that will be used. Some process documents record a particular moment in the project and on the next stages become outdated and obsolete. But they shouldn’t be deleted, because they provide information for implementing similar tasks or maintenance in the future.
Project Documentation Is a Must-Have
When developing a new product, documentation is a must-have. The whole team creates the documentation and stakeholders’ input is invaluable.
However, it’s important to remember that documentation should provide value and include only the most important information. The amount and the types of documentation should be adjusted to the particular project to help achieve its objective.
Relevant documentation should be delivered in a project according to best practices in a clear and instructive form and cannot interfere with the efficient creation of the product.
