A key task to ensure the quality of software development projects is to provide documents that gather what and how things were done. This documentation will help teams to easily prevent, detect and fix issues throughout the software development life cycle.
The number, contents and structure of quality documents depend on the project complexity and needs. This section describes some common documents that should be present in most software projects:
Requirements Document: describes the functional and system requirements of the solution. The main sections of this document are the following:
- General Description of the project including relationships with other projects or systems as well as constraints.
- User Requirements: list of functional requirements that describe the logic of the application. A good practice is to split to system functionality into components and provide the user requirements for each component. Each requirement should have an unique id.
- System Requirements: describe the technical requirements of the solution needed to meet the expected functionality. As with user requirements, it is recommended to split the system into components and use unique id for each requirement.
- Traceability Matrices: these matrices verify that all user requirements are covered by at least one system requirement and vice versa.
Design Document: describes the technical solution as well as other design aspects such as user interface. The main sections of this document are the following:
- Logical Model.
- System Architecture including software and hardware components, class diagram, relationships, etc.
- Component Description outlining their design, dependencies and constrains.
- External Interfaces describing the integration detail with other systems.
- Use Cases: it is a good practice to describe the system functionality using use cases that explain how actors and roles interact in the system.
- User Interfaces: include wireframes, mockups, story boards and any other graphic component needed to design the user interface.
- Traceability Matrices: they are useful to validate system components, use cases and requirements.
Admin and Configuration Document: describes how to admin, operate and maintain the system. The main sections of this document are the following:
- Installation Guide: includes all steps, components and dependencies to install and boot the complete system.
- Process Management: information about all services that include the system and how to start, stop and monitor them.
- Backups and Recovery: describes the backup policy and the instructions to recover the system.
- Configuration Files: details about all configuration elements that affect the system behavior.
Test Plan: contains the details of the system test activities. he main sections of this document are the following:
- Test Approach: general description of the functionalities to be tested, types of tests, tools or resources needed, dependencies, etc.
- Test Cases: list of the tests that will be performed. Each test case should include details such as unique id, system component that the test is validating, type of test (e.g.: SW/HW test, code inspection, document review, etc.), description, expected results and actual results.
- Traceability Matrix: verify that all system requirements are covered at least by one test case.
User Guide: it is the manual that explains to final users how to use the application. The main sections of this document are the following:
- General Description: explain the purpose of the application.
- Functional Description: a guide that describes all system functionality including steps and graphical examples.
- Troubleshooting: summary of known issues and their resolution.
Product Backlog: in Agile projects this document is equivalent to the Requirements Document. The product Backlog describes the functionality of the system using prioritized User Stories. It contains all functional and nonfunctional requirements as well as the acceptance criteria for each User Story.