TRD: What is it and how it helps Software Engineers manage their work

Software engineers follow a systematic approach for converting a business requirement/feature request into working code. For doing that the first step after getting the product requirements is typically to make a TRD i.e Technical Requirement Document. Its also known as Software Requirement Specification(SRS) in some other places. I’ll be explaining the process of writing a TRD in detail with the help of an example.

What is TRD?

It is a document consisting of the intended purpose, functionalities, implementation, and behavior of the feature you will work on. The idea is to do the intellectual heavy-lifting in the beginning so that all that is left is to follow the implementation and the plan mentioned in the TRD.

It helps in the following ways:

1. Gives clarity and structure in approaching the problem.
2. Serves as documentation for the feature and the thought process behind it.
3. Forces you to inculcate a habit of thinking about implementation first and then writing the code instead of the reverse.
4. Communicate the implementation details across the team so that all the engineers and PMs are on the same page, especially useful if you are working as a pair of frontend and backend engineers.
5. It’s easier to get the implementation reviewed by tech leads before writing code if it is documented somewhere.
6. Provides the team with a checklist of milestones with timelines.
7. Provides a basis for future work, if any.

As an engineer, it is essential to “think ahead”. Writing a TRD plan helps in that. Initially, an engineer will feel lazy or fatigue but the benefits outweigh the effort put into writing a TRD

Creating a TRD

I have seen other formats of TRD which tend to be meticulous, for this article I am going to explain a format that we at WorkIndia, after doing many trials and errors, found to be short and pragmatic as a startup.

Let’s say your Product Manager comes up with a business requirement to make a Referral System for Users.

The first step is to always get clarity on each requirement in detail before writing a TRD. The last thing you want is to get the requirement wrong and PM finds it during testing :D.

The product requirements are usually given in form of a Product Requirement Document (PRD). There is usually some back and forth in this phase with the PM in getting the exact requirements.

Let’s say the requirements to be developed in this example are:

1. Each user will have a referral code that he/she can use to refer other potential users on the platform.
2. Allow only valid referral codes to go through while signing up.
3. Provide the user with a list of names of their referred users.

Other features such as referral incentives are missed out intentionally for brevity.

TRD Template that we use at WorkIndia:

Here are the various sections in TRD in detail:

Section 1: Objective

Once the requirements are clear in your mind, start with the objective of what are you working on and why. The objective is a distilled version of features to be made along with their impact. For this example, the objective can be:

“Create a referral system which allows users to refer others to install the app, thus increasing the app downloads.”

Writing the objective clarifies why are we building the feature in the first place and sets a context for others.

Section 2: Implementation

This is the core of TRD, the objective of this section is to clarify your approach and divide the problem into subparts.

While developing a backend feature, I usually create:

1. Entity Relationship Diagram (ERD) for any database changes,
2. API contracts, and implementation of each API.
3. If it is a feature affecting users directly, like in this case, then we can include data instrumentation.

You can also go into more details and draw flow diagrams, Modules, code changes in any existing classes, etc. I’ll be sticking with writing ERD, API contracts, API implementation, and Data Instrumentation for this article.

ERD in this example can be:

API contracts along with their implementation in this example can be:

Having visibility of how the feature is performing in terms of its business impact is critical, it helps decide whether to roll out the feature to a larger population or discontinue it. Data instrumentation refers to thinking about events and dashboards views that we will need to create that visibility.

Events that we need in this example can be:

1. App lands
2. Referral section on app visited
3. Refer button clicked on
4. App install event via referral

After the feature is released, we can create a funnel using the above events on Metabase

Section 3: Test cases

This section provides the major functional test cases to be verified before any feature goes live on production, the checklist needs to be as exhaustive as possible as it saves a lot of hassle on coming up with the test cases later on after the development is done.

Some of the test cases in this example can be:

1. The referral code generated must be unique for every user.
2. On entering an invalid referral code, API should throw back an error.
3. On entering a valid code, the user should get successfully referred and entry of referred user should be created against referee in Referral table.
4. One user can refer multiple other users.
5. One user can be referred only once.

Section 4: Production deployment checklist

If your feature has any dependencies that must be taken care of beforehand, it’s better to write all the processes in the deployment checklist. It is an ordered list of processes you must do to get the feature live on production.

Production checklist in this example can be:

1. Run the migrations on the database.
2. Deploy the backend changes.
3. Deploy Frontend changes.
4. Monitoring.

Section 5: Efforts

The objective of this section is to divide the task in hand into major subtasks and give an estimated timeline for each milestone. Its easier to estimate the time of doing subtasks instead of the whole task. It also gives clarity to you and the team about the estimated time to completion of the feature and we can also keep an eye on whether the development of the feature is going according to timelines by measuring the time taken for each milestone.

Milestones along with its timelines in this example can be:

1. API changes — X days
2. Frontend changes — Y days
3. Testing and deployment — Z days

Total Efforts: (X+Y+Z) days

I have improved a lot by practicing writing TRD. Before TRD there used to be at least 4 - 5 back and forth with tech leads and PMs. After TRD, it has reduced to 1–2 in most cases.

So, a TRD is a powerful tool that, in my opinion, every software engineer should use to manage their work. It saves a lot of time, work, and energy and makes our lives easier as software engineers :D