Software documentation is a broad term referring to anything written down for the purposes of recording, explaining or detailing the purpose and operation of a software project from conception to completion.
In a previous article, we talked about why developers should be obsessed with documentation and covered the importance of having documentation in place and emphasised the fundamental reliance we have on documentation.
Organisations working on software projects where multiple parties are involved may use many different types of software documentation to ensure there is clarity and commonality on the goal of the project amongst stakeholders.
Taking the time to write useful types of software documentation will provide completeness to a project by improving the management, scalability and maintainability of the resulting product.
Paying attention to software documentation for an individual or a team can be seen as an investment that will create benefits through increased productivity and optimisation of processes.
Documentation and proper management can also pay off by avoiding potential pitfalls in software development such as technical debt.
This article lists 5 basic types of software documentation that should be in place for a development project, either solo or team-based.
Note: Not all types of software documentation on this list need to be written for a single project but a combination of several should be selected depending on the nature of the project. Whether more or less documentation is needed for your project will depend on its scale and complexity.
1. Requirements Specification
Requirements are one of the fundamental types of software documentation and are one of the first forms of documents written in the starting stages of a project.
Requirements as a summary describe the purpose of a project and software requirements should capture the desired functions of the software.
At an organisational level, stakeholders will usually list the requirements for a software product based on the needs of the market. The relevant people in the project then work towards creating a set of requirements that describe what the software should achieve to meet these needs.
At an individual level, a requirements document should work the same and can list the desired functions of a software project according to what the end-user anticipates.
As a starting point, a requirements document can be drawn up by asking some of the following questions:
- What is the purpose of the software?
- How will the software solve a particular problem?
- What are the minimum features that should be implemented? – also referred to as a Minimum Viable Product (MVP).
- How will specific use cases be met?
- What makes the software profitable?
2. Software Design
While the requirements document is focused on what the software should do, documentation on software design focuses on how it does it.
A design document is one of the types of software documentation that will largely vary from project to project. It can be a high-level overview of the software implementation or can go down into low-level details of the architecture and software flow.
A software design document commences roughly when the project is ready to move from planning to execution and ideally should be in place after the requirements document is written.
A design document is handed over to the developers who use it as a guideline to understand how the code should be built.
As an overview, a software design document may contain the following:
- System design and architecture
- State diagrams
- Use case handling
- Interfaces to internal and external components
- Templates and workflows
- Coding standards and naming conventions
3. Source Code Docs
These can be one or several documents detailing any useful information that can be recorded about the source code of a project.
In line with good development practices, source code should be managed by a software versioning control system such as git. Apart from source code, a repository of a project will be expected to contain some supporting documents. This is usually technical information aimed at developers working on the project.
A README file is associated with source code repositories and will provide a general overview of the project and how to use it. It will also typically explain what a developer needs to know to work with the source code and instructions on setting up the development environment.
If you choose to have only one form of documentation in your source code repository, it should be a README file. README files have become part of the unofficial standards in source code management and are now considered the bare minimum documentation that should exist within every software repository.
Other source code documentation include block diagrams and flow charts to provide visual information on the code structure. Release notes are another form of document that tracks changes that occur throughout different versions.
Here’s a checklist of items you can place in a source code repository:
- README file – Detailed instructions and information needed for anyone to get familiar with the structure of the source code files and how to work with them.
- CONTRIBUTION file – For open source projects this will be included in the repository describing what contributions can be made to the project and the steps on how to make them.
- Software flow chart – Describing a high-level overview of the software operation and sequence of flow.
- Technical reference manuals – Containing the functions, libraries, APIs, or any other components developed for the project.
- Release notes – Records the changes between versions.
4. Testing Requirements
Testing is a critical exercise for any project that if done correctly will catch any bugs or defects before it reaches the end-user. For such an important exercise it is therefore also crucial that a document is in place that captures the testing design and criteria for the project.
As deadlines approach, testing is often seen as a step that can be neglected to speed up time to market for the product launch.
However, ensuring the software is tested according to good standards and procedures will improve confidence in its robustness and prevent future complications that can arise such as in the form of technical debt.
Documents on testing should list the requirements for testing and detail the criteria to be met to approve the software as functional for the desired application.
Having test specifications in place will ensure testing remains a significant activity throughout all stages of the project and will align everyone involved on the testing procedures to be followed.
Test documentation can be written before, during or after completed development work and will depend on the software development processes adopted for the project.
Here is a checklist of items that may be included in a testing requirements document:
- Description of test types, plans and strategy for the project
- List of test cases and scenarios
- Functional testing checklist
- Regression testing workflow for each release
- Guidelines for reporting and tracking defects
- Test report templates
5. End-User Instructions
These types of software documentation are written for the actual users of the application. As a result, they usually will not contain technical detail but rather information on the software from the viewpoint of an end-user.
Documents written for the end-user should also contain some information on how to deal with any issues that may arise. For example, as users raise questions about the product, this can be gathered and compiled into a list of Frequently Asked Questions (FAQ).
User-focused documents should also contain enough information about the features of the product that will allow easy usage.
Here are some types of software documentation written for the end-user:
- Installation and configuration manuals
- How to tutorials
- Feature descriptions
- FAQ
- Troubleshooting guidelines
Conclusion
These types of software documentation cover information that should be written down across all stages of a development project.
The requirements should ideally be drawn up before any coding begins while the software design document details how the software will meet those requirements.
Source code documents provide technical information for the development team on how to work with the project and test-related documents describe the testing procedure to ensure the software is functional.
Finally, end-user instructions detail what anyone needs to know to use the resulting application.
While there are many more types of software documentation that can exist for a project, these 5 types should get anyone or any team started with the basics of ensuring a software project is well documented and will improve its scalability and maintainability.
Check out other articles you may be interested in below: