Writing Technical Specification, and Why it Matters
By: Anggie Aziz
Tags: Software Development, Engineering, Process, Software Engineering, Agile

Why tech spec?

Imagine if you jump to coding right after receiving project requirements, you’ll either repeatedly changing the design during the implementation, delivering a buggy product, or even jump back to where you started because the result is “not what’s expected”. Even worse, if you give a promise based on your intuition, and then you found out that the deadline is too early, or the budget isn’t enough.

Chart picture by Raygun

Remember the chart above? I believe you saw it somewhere in some form. Basically, it says “the earlier it is detected, the cheaper”. The same applies to design changes.

For me, technical specification is a document to outline how we are going to tackle technical issues in order to achieve a goal. Usually, this document will be written by senior engineers or leads before implementation.

Furthermore, below are the benefits of writing tech spec:

Knowing the unknowns , when you breakdown all the work, you’ll then realise the possible blockers, potential performance issues, something missed (such as security approval, or you just forgot to update a particular script), possible risks, etc

, when you breakdown all the work, you’ll then realise the possible blockers, potential performance issues, something missed (such as security approval, or you just forgot to update a particular script), possible risks, etc Documentation , tech spec can be revisited anytime required, such as on an audit (can also act as decision/design logs)

, tech spec can be revisited anytime required, such as on an audit (can also act as decision/design logs) Work consensus , by getting approval from the tech spec’s reviewers, meaning that they've agreed with the solution

, by getting approval from the tech spec’s reviewers, meaning that they've agreed with the solution Reduce the effort on explaining to parties , when you need to explain the work to team members or other teams, you can always bring this tech spec to make them easier to understand

, when you need to explain the work to team members or other teams, you can always bring this tech spec to make them easier to understand Better task distributions , the team can easily understand what will be done and feeling confident to work on it because the tech spec was agreed by required parties

, the team can easily understand what will be done and feeling confident to work on it because the tech spec was agreed by required parties Faster development and better quality , things are prepared and the team understand what to do before the execution

, things are prepared and the team understand what to do before the execution Better estimation, because you know what to do

because you know what to do Cheaper failure, because design changes and bugs will be detected earlier

Prerequisites

Requirements are the core of software development, so ensure the requirements are clear and you understand it correctly. I recommend you to write it in a document (if there isn’t) and get an agreement with your project manager or stakeholder about it. Furthermore, I’d recommend you to check out “Software Requirements” part of SWEBOK (an ISO for software engineering) to better understand this subject.

Suggested Format

The below format is the most ideal tech spec format based on my experience, but feel free to change it according to your requirements because different context might need different treatment.

Head

Author , the tech spec’s author name

, the tech spec’s author name Reviewer(s) , the tech spec’s reviewers name

, the tech spec’s reviewers name Status, it’s either stable or draft (default), to set the reader’s expectation

Table of Contents

For reader to easily navigate through the document.

Introduction

Business requirements , can be links of the related requirements document and story/epic link. This is the goal of your tech spec, so it’s really important to put this

, can be links of the related requirements document and story/epic link. This is the goal of your tech spec, so it’s really important to put this Glossary, any jargon that is related to specific domain, or perhaps not everyone knows

Solution

Technical decision , describe why you choose this technical decision over the others, including proof of concept, performance impact, etc

, describe why you choose this technical decision over the others, including proof of concept, performance impact, etc Implementation , describe the current state and suggested changes that must be done to satisfy the requirements based on the technical decision that was made

, describe the current state and suggested changes that must be done to satisfy the requirements based on the technical decision that was made Metrics , list of success metrics of the work, or it can be a list of definition of done

, list of success metrics of the work, or it can be a list of definition of done Possible risks, anything that might harm/block this solution. It is recommended to include these components: Possible Risk (what is the risk), Preventive Action (Actions that can be taken to prevent or reduce the risk). e.g:

Plans

Test plan , how the work should be tested

, how the work should be tested Release plan (usually checklist), how to release the work to production, it is recommended include these components: Who (who will do it), Action (what will be done)

(usually checklist), how to release the work to production, it is recommended include these components: (who will do it), (what will be done) Rollback plan, as a contingency plan when something went wrong. It is recommended to include these components: Fail Type (e.g deployment error, test failure, SQL error), Scenario (e.g fail to execute migration script), Solution (e.g if this then that, if that then this), Appendix (e.g script to clean broken data caused by the failed migration)

Supporting resources

Any resources that are related and able to support the tech spec.

Almost there!

Remember to ask relevant parties to review your tech spec, and iteratively improve the document until an agreement is reached. Then, you can change the tech spec status to Stable and distribute the work to team members.

Conclusion

Writing a technical specification requires an extra effort at the early process of your development cycle. But, the benefits in the long run are well worth it. However, if you still doubt or not used to it, you can try to write it in one or two epics of your project and see how it goes. Furthermore, I also recommend you to read this article to broaden your knowledge.