At DISQO, the Technical Requirements Document (TRD) forms our path for project development and maintenance. The TRD is a definitive source of truth that bridges the gap between what the business requires and what the engineers will build. The document is a high-level technical overview and more detailed technical specifications.

TRDs should be easy to read and understand, and readers should come away thoroughly grasping what goes on behind the scenes of a project. Beyond being an informational document, the TRD must pass proposal reviews, and is considered finalized after approval.

At this point, the TRD is considered to be a clear-cut contract between the engineers and the business.

My team is primarily focused on building microservices and in the following post, we will be focusing mainly on TRDs for microservices.

Teams and team managers may use a variation of the forthcoming in their own TRDs. Some teams have opted to take out the preamble since it is often stock text. Others integrate the FAQ content into the previous sections for a more narrative-style TRD.

Content Responsibilities (Manager vs. Engineer)

Before we get into the specifics of the structure and content of a TRD, let’s talk about the responsibilities of the manager versus the engineer in the creation of this document.

The manager writes the first draft based on content from the project’s Business Requirements Document (BRD). The BRD is a business-focused document that outlines the goals that the business is trying to accomplish with the proposed product. After the manager has written their part of the TRD, they hand it off to the engineers on their team. The engineers collaborate on adding content that shows how they plan on building the product.

Manager Responsibilities

The manager is in charge of bridging the business requirements and the technical details of a project. Managers need to deeply understand the big picture of the project and explain it clearly to their engineers.

Managers are responsible for the following parts of the TRD:

• Defining the connection between the Business Requirements Document (BRD) and the technical requirements.
• Defining service-to-service communication between the current project and any other services that it’s required to interact with.
• Making sure the document is read and reviewed by all stakeholders after the engineers have completed their part.

Engineer Responsibilities

The engineers are in charge of defining all the technical requirements for the project as well as researching any details that need to be defined.

The engineers are responsible for the following parts of the TRD:

• In the case of breaking down a monolithic application function into a microservice, the engineers spend time analyzing and understanding the current monolith implementation.
• Defining all technical details for the service being built, and being mindful of the product’s expectations and limitations.
• Making changes that stakeholders request.

Structure and Content

Now, let’s take a look at the structure and content of a TRD. Structure refers to the architecture and organization of the TRD, and content refers to what goes in a TRD. We have streamlined our TRDs with the boilerplate sections that we’ll go through below.

Preamble

The Preamble sets the expectations for what the document is and what it contains. Basically, it defines the scope of the document.

Environments

This section defines all of the environments to be created for the project.

Project Overview

The Project Overview defines the business objectives and project goals. It’s written in non-technical language and when successful, puts the entire TRD into context for the reader.

FAQ

The FAQ section contains questions we anticipate will arise. Here, we outline certain limits for the project as well as cover any common queries a reader may have.

Some questions most likely answered in this section are as following:

• Who is this project for?
• If applicable, how do other internal engineering teams integrate with this project?
• What’s outside the scope of this project?

Now we’re going to talk about the how. We start with the most integral part of our projects, the interface to the end-user, which in our case means defining the endpoints of a microservice.

API Endpoint Definitions

This section contains a list of all the endpoints and a link to the Swagger file. The Swagger file is considered as part of the TRD even if it’s an external link, so it should be finalized by the time the TRD is being reviewed.

Diagrams

This section contains both component and sequence diagrams. These diagrams help the reader understand where the project sits in the company products ecosystem, how it interacts with its neighbors (if there are any), and exactly how requests or queries flow through all the services.

While we only require one component diagram, the amount of sequence diagrams varies depending on the service, number of endpoints, and how many interactions are vital to the project.

Database Schema

The Database Schema section contains any database details. The content here differs greatly from project to project. In some cases, we need to create a new database and all its tables. In other cases, we need access to certain tables in existing databases.

Security and Authentication

Here, we define what the communications to the service will look like from a security perspective. We specify whether communications are service-to-service or client-to-service, and what steps need to be taken for the interaction to succeed.

Tech Stack Overview

This section contains a complete list of all the languages, frameworks, and libraries being used. It also contains our standards for code quality, maintainability, and scalability.

Observability

This section contains a list of the project metrics that are being tracked, and the alerts created to stay on top of unexpected behaviors. The metrics and alerts guarantee the project’s health and the quality of the service.

Capacity Planning

This section contains the expectations of the project’s usage, and how we plan on handling the load. Capacity planning also includes scaling preparations made for cases where the usage load exceeds or doesn’t meet expectations.

Deployment Strategy

This section contains several subsections defining what is actually being deployed, what the topology of the deployments is going to be, and the CI/CD process that is going to be implemented (defined with a diagram).

Recently there has been an increased interest for more precise documentation for all our projects, and I agree that we can improve. A big issue many engineers encounter when entering a new job or even just interacting with another team’s projects is not knowing where to start or how to make use of certain parts of the project. To improve cross-team transparency, I recommend having two additional sections, Documentation Strategy and Testing Strategy.

The Documentation Strategy should outline all the avenues an engineer is going to have in their search for more details about the project and its current state. The Documentation Strategy should lower the time it takes to get completely up-to-date on a project and cement documentation as a requirement for development.

Additionally, I suggest having a section outlining the project’s Testing Strategy. The testing strategy will aid in creating a Definition of Done for your project’s tasks. Definition of Done is an extensive topic that deserves its own article, but I felt it necessary to at least mention it.

The Technical Requirements Document overall acts as a build contract, or agreement between the business, engineering manager, and engineers who are assigned to build this product. While we do work off of a template, it’s critical that we remain open to changes while keeping the integrity of the original document.

We’re hiring! Check out our Careers page for a list of all open positions.