Documentation in software engineering is the umbrella term that encompasses all written documents and materials dealing with a software product’s development and use. All software development products, whether created by a small team or a large corporation, require some related documentation. And different types of documents are created through the whole software development lifecycle (SDLC). Documentation exists to explain product functionality, unify project-related information, and allow for discussing all significant questions arising between stakeholders and developers.
On top of that, documentation errors can set gaps between the visions of stakeholders and engineers and, as a result, a proposed solution won’t meet stakeholders expectations. Consequently, managers should pay a lot of attention to documentation quality.
The documentation types that the team produces and its scope depend on the software development approach that was chosen. There are two main ones: agile and waterfall. Each is unique in terms of accompanying documentation.
Waterfall is a linear method with distinct goals for each development phase. Teams that use waterfall spend a reasonable amount of time on product planning in the early stages of the project. They create an extensive overview of the main goals and objectives and plan what the working process will look like. Waterfall teams strive to create detailed documentation before any of the engineering stages begin. Careful planning works well for projects with little to no changes in progress as it allows for precise budgeting and time estimates. However, waterfall planning has proven to be ineffective for long-term development as it doesn’t account for possible changes and contingencies on the go. According to PMI’s 9th Global Project Management Survey, the Agile approach is used by 71 percent of organizations for their projects.
The agile approach is based on teamwork, close collaboration with customers and stakeholders, flexibility, and ability to quickly respond to changes. The basic building blocks of agile development are iterations; each one of them includes planning, analysis, design, development, and testing. The agile method doesn’t require comprehensive documentation at the beginning. Managers don’t need to plan much in advance because things can change as the project evolves. This allows for just-in-time planning. As one of the Agile Manifesto values suggests, putting — “working software over comprehensive documentation -“, the idea is to produce documentation with information that is essential to move forward, when it makes the most sense.
Today, agile is the most common practice in software development, so we’ll focus on documentation practices related to this method.
The main goal of effective documentation is to ensure that developers and stakeholders are headed in the same direction to accomplish the objectives of the project. To achieve them, plenty of documentation types exist.
Adhering to the following classifications.
All software documentation can be divided into two main categories:
Product documentation describes the product that is being developed and provides instructions on how to perform various tasks with it. Product documentation can be broken down into:
System documentation represents documents that describe the system itself and its parts. It includes requirements documents, design decisions, architecture descriptions, program source code, and help guides.
User documentation covers manuals that are mainly prepared for end-users of the product and system administrators. User documentation includes tutorials, user guides, troubleshooting manuals, installation, and reference manuals.
Process documentation represents all documents produced during development and maintenance that describe… well, process. The common examples of process documentation are project plans, test schedules, reports, standards, meeting notes, or even business correspondence.
The main difference between process and product documentation is that the first one record the process of development and the second one describes the product that is being developed.
System documentation provides an overview of the system and helps engineers and stakeholders understand the underlying technology. It usually consists of the requirements document, architecture design, source code, validation docs, verification and testing info, and a maintenance or help guide. It’s worth emphasizing that this list isn’t exhaustive. So, let’s have a look at the details of the main types.
A requirements document provides information about the system functionality. Generally, requirements are the statements of what a system should do. It contains business rules, user stories, use cases, etc. This document should be clear and shouldn’t be an extensive and solid wall of text. It should contain enough to outline the product’s purpose, its features, functionalities, and behavior.
The best practice is to write a requirement document using a single, consistent template that all team members adhere to. The one web-page form will help you keep the document concise and save the time spent on accessing the information. Here’s a look at an example of a one-web-page product-requirements document to understand various elements that should be included in your PRD. Nevertheless, you should remember that this isn’t the one and only way to compile this document.
One web-page product-requirements document created by using Atlassian Confluence, the content collaboration software
Here are the main recommendations to follow:
Make all this information more comprehensive by using the following practices:
Software architecture design documents include the main architectural decisions. We don’t recommend listing everything, but rather focus on the most relevant and challenging ones. An effective design and architecture document comprises the following information sections:
Design document template. Discuss and form a consensus with stakeholders regarding what needs to be covered in the architecture design document before it has been created and use a defined template to map architectural solutions.
Architecture & Design Principles. Underline the guiding architecture and design principles with which you will engineer the product. For instance, if you plan to structure your solution using microservices architecture, don’t forget to specifically mention this.
User Story description. Connect user stories with associated business processes and related scenarios. You should try to avoid technical details in this section.
Solution details. Describe the contemplated solution by listing planned services, modules, components, and their importance.
Diagrammatic representation of the solution. Identify the diagrams that need to be created to help understand and communicate the structure and design principles.
A source code document is a technical section that explains how the code works. While it’s not necessary, the aspects that have the greatest potential to confuse should be covered. The main users of the source code documents are software engineers.
Source code documents may include but are not limited to the following details:
Try to keep the document simple by making short sections for each element and supporting them with brief descriptions.
There are different types of testing documents in agile. We have outlined the most common:
A test strategy is a document that describes the software testing approach to achieve testing objectives. This document includes information about team structure and resource needs along with what should be prioritized during testing. A test strategy is usually static as the strategy is defined for the entire development scope.
A test plan usually consists of one or two pages and describes what should be tested at a given moment. This document should contain:
A test case specifications document is a set of detailed actions to verify each feature or functionality of a product. Usually, a QA team writes a separate specifications document for each product unit. Test case specifications are based on the approach outlined in the test plan. A good practice is to simplify specifications description and avoid test case repetitions.
Test checklist is a list of tests that should be run at a particular time. It represents what tests are completed and how many have failed. All points in the test checklists should be defined correctly. Try to group test points in the checklists. This approach will help you keep track of them during your work and not lose any. If it helps testers to check the app correctly, you can add comments to your points on the list.
This document should describe known problems with the system and their solutions. It also should represent the dependencies between different parts of the system.
As the name suggests, user documentation is created for product users. However, their categories may also differ. So, you should structure user documentation according to the different user tasks and different levels of their experience. Generally, user documentation is aimed at two large categories:
The documentation created for end-users should explain in the shortest way possible how the software can help solve their problems. Some parts of user documentation, such as tutorials and onboarding, in many large customer-based products are replaced with onboarding training. Nevertheless, there are still complex systems remaining that require documented user guides.
The online form of user documentation requires technical writers to be more imaginative. Online end-user documentation should include the following sections:
In order to provide the best service for end-users, you should collect your customer feedback continuously. The wiki system is one of the more useful practices. It helps to maintain the existing documentation. If you use the wiki system you won’t need to export documents to presentable formats and upload them the servers. You can create your wiki pages using a wiki markup language and HTML code.
System administrators’ documents don’t need to provide information about how to operate the software. Usually, administration docs cover installation and updates that help a system administrator with product maintenance. Here are standard system administrators documents:
Process documentation covers all activities surrounding the product development. The value of keeping process documentation is to make development more organized and well-planned. This branch of documentation requires some planning and paperwork both before the project starts and during the development. Here are common types of process documentation:
Plans, estimates, and schedules. These documents are usually created before the project starts and can be altered as the product evolves.
Reports and metrics. Reports reflect how time and human resources were used during development. They can be generated on a daily, weekly, or monthly basis. Consult our article on agile delivery metrics to learn more about process documents such as velocity chats, sprint burndown charts, and release burndown charts.