Why you should write a technical analysis document

Over the past few years, I have authored various technical analysis documentations. Today I will share why I love writing technical docs and how it helps me strengthen my understanding of requirements and finalize technical approach before writing a single line of code.

Writing technical documentation might not be a priority when we are always on the clock for shipping deliverables, bug fixes, managing new releases, iterating/redesigning the new product to incorporate customer feedback, shipping new features, tweaking existing features. [No offense to anyone]

Product delivery is the end goal, but how we end up there matters as well.

Personally putting some thought into technical aspects, jotting down [need not to be A fancy template ], and getting it reviewed by peers helps put things in perspective and catch blunders ahead of time if any.

In the interest of the discussion, let’s assume we are building something complex and not just any other “Calculator” app

If you love writing technical documentation or if it is an exercise that you follow in your organization. Kudos to you. 👏 👏

When to write technical documentation?

You might say, why would I spend time writing technical documentation when I can just get a head start by coding right away…!!?

If it has been working for you so far, it is wonderful!

It is a delicate balance. There is no perfect answer for this question, it all depends on the scope of the work, breaking changes on existing functionality, your change affecting dependent teams.

Don’t write it for others, write it for yourself

How does it help me?

1. Defines the scope of the deliverable
   While building a feature, we may have multiple discussions across the teams like backend, product, design, and front end engineers. Eg. Depending on the complexity of the feature, it could be planned as subsequent releases. In that case, you will understand what will be delivered as MVP and extend the implementation further.
2. Adopt better solutions and incorporate feedback
   Evaluate the alternative approaches for achieving the same result. Peer feedback in incorporating the best practices. There is a great deal of learning when you adopt from other’s experiences.
3. Identify the non-functional requirement
   Performance optimizations, device/browser compatibility, logging app events to Firebase Analytics, New Relic, etc.
4. Acts as historical evidence
   Building and improving software is a continuous process, looking back 6 months you might not remember what and why decisions were made while developing the feature.
5. Easy handover of projects
   Simply providing technical docs while handing over the project might not suffice, but it has a silver lining. It provides the new team members to glance over the project decisions, approaches, and challenges without delving into the source code.
6. Derive ETA effectively
   In JIRA, we break down “EPIC” into multiple user stories and further into SubTasks that will be tracked over the sprints.
   
   Although SubTask “Persisting user data” is the smallest trackable chunks, this SubTask in itself might require further analysis that will answer the following questions :
   1. For a new project, you might want to evaluate different approaches for data persisting.
   2. How to persist user data? Is it inbuilt into the platform or introduce a third-party library?

Note: your organization might follow a different workflow

7. Fail-safe mechanism
It acts as a soft binding reference document among the team. Also, doesn’t mean that blame goes around on everyone if something wrong happens. 😳

8. Identify product risks ahead of time
This might be a rare occurrence, but trust me it happens. You might be able to identify the certain feature that areas cannot be completed within the timeframe or there are many technical challenges. It is ideal to involve stakeholders in such discussions ahead of time rather than writing 90% of the code and then presenting the product risks.

What to include in a technical document?

The document can be as comprehensive as it can be. I have seen a few technical documentations where line by line change is also documented. But to get started following the template might be enough.

• Brief
  what to expect from this document. There are two parts:
  1. Background: what is the motivation behind building this
  feature/module
  2. Summary: the purpose of this document
• Target Audience
  whom this document is intended for
• Milestones
• Technical Analysis
  1. Flow charts [Optional]
  2. API
  — List down the API endpoints + sample responses that will be used
  — Identify if any new API is required. Attach a sample data contract post
  discussions with backend engineers
  3. Source code
  — Introducing a third party library [if any]
  — Refactoring the existing code to implement the new feature
  — Introducing new code files and defining the structure with DRY, AHA
  principles
  — Modifying the existing files
• Non Functional Requirements
• Test Cases

You might not have all these details upfront while documenting, I would still suggest getting started with all you know and filling the gaps as and when you understand.

Yes, writing technical documentation can be time-consuming or you may not enjoy it. But I personally think the benefits outweigh the other aspects. What do you guys think?