How to write requirements for a project. Documentation template
Freeing the developer from additional questions: Every aspect of the project must be clearly described so that the developer can focus on completing the tasks.
Ensuring a common understanding of the project: All project participants must quickly and effectively understand the purpose of the product or function, as well as its technical design.
So how does an ideal dock work? It has the following structure:
BRD&SRS.
Business logic
UI logic
Product analytics
BRD&SRS
BRD&SRS – is a document that brings together the main aspects of the development, including a description of the project's goals, history, needs and values, interested stakeholders, project boundaries and constraints, functional and non-functional requirements, and key issues and problems
MAIN GOAL. Here we need to describe the purpose of the product/development.
Background and summary of the essence of the project.
Statement of needs and value of the project. In this section, we capture the needs that are satisfied by the development and the value that the development will bring. Use effectively in combination with BACCM Canvas.
The goal of the project is SMART.
PEST – analysis of the competitive environment. Analysis of the external environment: political, economic, social and technological factors.
Stakeholders of the product. We indicate internal and external project participants. A good practice is to create a stakeholder matrix or do a stakeholder analysis using a mindmap.
Project boundaries and restrictions. We define development boundaries, team responsibilities (for which stages of software development the team is responsible) and restrictions, including business rules and regulatory requirements. It will be much easier to analyze the requirements from regulators if in the previous paragraph we made a mindmap of stakeholders.
Functional requirements and features. In this section we describe the functionality of the product being developed. I prefer to describe them in user story format, indicating the user's role in the system. “As a buyer, I want to be able to order goods to a collection point.”, “As an administrator at a collection point, I want to be able to scan a user’s QR to obtain detailed information about their products. But it is possible to describe TF in USE CASE format. It is also necessary to record the use case diagram so as not to forget or lose some of the development functionality.
Interface requirements. We indicate the requirements for design and user interface. This item can be excluded if the design has already been developed.
Non-functional requirements. The list of NFTs can be extensive, but here are some key aspects:
Performance and reliability. We carry out calculations of RPS, throughput and storage size.
Scalability requirements.
Security requirements. Recently, there has also been a popular opinion that security requirements can be classified as functional requirements, but in my experience, each company has its own approach, so it will not be critical if we classify security as an NFT.
Questions and problematic issues.
Thus, our document combines both business and technical requirements, ensuring a complete understanding of the project for all its participants.
Business logic
This section includes the following artifacts:
Sequence diagram for each flow (look at the use case diagrams)
Database diagram. This can be either an ER diagram or a class diagram.
API Description. It depends on the accepted standards. Somewhere they use Swagger, and somewhere they write with pens according to accepted templates. The main requirement is that the services be described clearly not only for developers, but also for other team members.
Activity diagram for each flow. What I usually do is create action types (network action or request, user action, UI action, SDK logic) and mark each action with a specific color. This approach perfectly reflects the user flow, user and system actions.
Component diagram. It is necessary to update or create a component diagram that displays the service map and the role of the project being developed in it.
UI logic
This section serves as a dock for front-end and mobile developers and includes the following artifacts:
UI screens. This document describes each screen. Namely, after receiving the design, we take a screenshot for each step, attach it to the dock and describe the operation of this screen. That is, we describe what UI elements we have, describe the logic of their operation and how they react to user actions.
Localization. Here we give a name to each element that has a caption and indicate the localization in the required languages. This block is optional, as it depends on the project’s approach to texts. Somewhere it is hardcoded, and somewhere it is stored in configs. Therefore, it is important to take away the main idea of this document – the reuse of elements with texts, as well as the storage of text not in the developer’s code.
Screen navigation. Although we've already created a detailed activity diagram to describe all the logic of the project, it's always useful to have an additional activity diagram that focuses solely on navigation between screens.
Product analytics and logs
It is preferable that a product analyst or product owner be responsible for this section. But life is not ideal, so let’s discuss what this section should contain.
Description of the metrics used. It is necessary to describe all stages of the user funnel, as well as technical and product metrics.
Description of events. This section records events necessary to calculate certain metrics and analyze user actions in the product. These events can also help identify possible incidents or problems.
List of required logs for incident analysis and analytics.
In the next article, I will provide examples of filling out each section and create a public space in Notion for easy use, so that everyone can write quality documentation. I suggest discussing in the comments what sections and items can be added to this template.
I also write about systems analysis and a career in it telegram.
