Writing technical specifications is a very common requirement if you work as integrator, solution architect or technical manager. In this article you will find some tips on what to do and what to avoid when writing technical specifications.

Table of Contents

• Introduction
• Writing technical specifications – What should you do?
  • Ask questions to clarify requirements
  • Ask questions about the environment
  • Do your homework, learn about technical parts and try to make a prototype
  • Understand the “rough estimation” concept
• Writing technical specifications – What should you avoid?
  • Don’t assume without question
  • Don’t let other opinions intimidate you
  • Don’t be “that” guy/girl
  • Don’t forget about support while writing technical specifications
• Recommendations for writing high quality technical specifications
• Conclusion

Introduction

Usual process is quite simple. Management of your company want’s to introduce something new. For example, new feature of your software or user story. On the other hand, you might have to integrate external API to your software.

As solution architect, you have to examine technical details and initial requirements. Furthermore, you should come up with rough technical proposal and time-frame needed for the implementation.

Firstly, good planning is a key for the success here!

Secondly, keep in mind that specifications will be implemented after this initial planning. Management will expect implementation of these requirements within the suggested time-frame.

Finally, and this is very important, providing an estimate is not a one-way task. It is actually a tennis match between development team and requirements. Therefore, writing technical specifications and estimates should not happen in a “first try” but in several rounds and refinements.

Rule number 1 – Do not have a lack of confidence. Try to put things in a perspective. Try to understand what is expected and what is not expected from you in this step.

Writing technical specifications – What should you do?

To make this more simple, we will walk trough an practical example of writing technical specifications.

Requirement: Two systems should be combined to work together. The first system has a REST API and the second system accepts CSV files used to consume data. You need to make a system that would synchronize user accounts between these two systems

Ask questions to clarify requirements

You need to get more information about the expectations of a product owner (that might be client, manager or anyone else really).

For these requirements, you could ask:

• Firstly, what does the user synchronization means? Is this creating of new users only or deleting them as well? Furthermore, do you have to update changes as well to the existing user accounts?
• Secondly, is this synchronization “full” or “delta”, meaning will you receive complete database state or only changes made in some period of time?
• Thirdly, which data should match (name with name, address with address, email with account name, etc.)? If possible, a table with mappings would be good.
• Finally, which parts of this use case are generic? Which parts might reappear or be reused from previous requirements?

Ask questions about the environment

Setting correct limitations when writing technical specifications is the very important thing. Meaning, for that your feature will not be used. Meaning, in what environment will this feature be used, and which conditions are fulfilled before this feature can be used. For example, what kind of grant_type is provided by API? This is a definition of the environment.

Therefore you could ask:

• Firstly how should two systems communicate? Will the IP addresses be whitelisted?
• Secondly, are there some special ports that should be opened? For example, SSH port for SFTP communication?
• Thirdly, what type of database is used for data storage? What kind of grant_type is provided by API? Password-based or authorization token-based?
• Finally, what amount of users is expected, 100s, 1000s, or millions?

As you can see, answers from these questions can and will influence your coding process very much.

Do your homework, learn about technical parts and try to make a prototype

This step is quite simple. If you are able to make a quick prototype or simply learn more about technical side of story it will help you determine time-frames.

For this step, it is very important to be able to quickly learn the new programming language, concept, or protocol.

Understand the “rough estimation” concept

When someone asks you for a rough estimation, how do you react? Usually, at this point you don’t have enough information to give a meaningful feedback.

So, what should you do and how to handle “rough estimation” request.

Firstly, understand that “rough estimation” should not be obligatory for you. It is an initial estimation which can be very wide. Furthermore, it can borderline with “guesstimate”.

For example, if someone has a feature in mind you might give a rough estimate as:

• Less than 1 day of work
• Between 1 and 2 days
• Less then a week
• More than a week

Secondly, understand what is a benefit of having a rough estimate. It is not about the exact number of hours. Rough estimate is not about pushing you to do something quicker, but about planning.

If something seems complex and you estimate it to “more than a week” this is ok. You don’t have to know a details about it. But, you do have to know how to continue pursuing this.

Finally, you need to have the idea on how to continue after rough estimate phase. For example, if something is “more than a week”, then you need to propose ways to make it more understandable or break it into smaller tasks.

For example, if someone from my team tells me that something is “more than a week” then I would try to split that activity into smaller tasks. Therefore this activity would have:

• Research tasks (find out more about environment)
• Build a prototype task
• Develop one aspect of the feature
• Furthermore, develop another aspect of the feature
• Make working MVP. Note, there is a nice article on How to Build an MVP in the right way (text is from 2018)
• Test everything
• Deploy
• Monitor and react

2020-04-14 Update: I was informed about one more very detailed and interesting article on How to Build an MVP (Minimum Viable Product) made by Andrej Gajdos.

Writing technical specifications – What should you avoid?

Here is a list of things to avoid. If you do these things, your brain will turn to dust. Your life will become an empty hole of nothing. Bugs will crawl all over your code and in your bed. Your weekends will turn into work. Every moment will turn into slow suffering, unicorns will die, ozone layer will be destroyed, etc. You get my point.

Don’t assume without question

You should never assume without question. You can assume something, but only if you use it as a reason to ask question.

• Example: I assume that we will execute synchronization once per day. Is this correct or shall we execute it in some other frequency?
• Example: I assume that client will open his ports and whitelist our IP addresses. Is this correct, or we need to find some other way to establish connection?

Don’t let other opinions intimidate you

Writing specifications is a process that involves two or more sides. There will be different ideas on how to solve the problem. Therefore, everyone will not agree with your idea. Also, some people will openly hate your idea.

This is normal.

When someone present idea in front of the group it is normal to get opposite opinions. Also, it is completely normal when someone challenges your idea.

The important thing here is how will you react.

For example, you can react by defending your self or being all aggressive about it. This is not a very good way to go.

On the other hand, you can ask questions.

For example:

• Why do you think my idea is not good enough? How would you improve it?
• Why do you think this is taking too much of a time? Can we measure it against something else?
• Why do you think that we are getting into too much technical details?
• Why is this too detailed for this meeting? Who should talk about this?
• How would you improve it?

Don’t be “that” guy/girl

When a team is writing technical specifications there is always a person who sees only problems and immediate failure of that project. Don’t be that person.

It is important to think about all of the possible issues, problems or challenges but this should be constructive. However, it is not easy talking about issues and keeping a positive note.

This is something that you learn with a years of experience. If you know how to do this, super. If not, just keep in mind that a positive approach will be appreciated by everyone. Finally, it will help others help you.

Don’t forget about support while writing technical specifications

This is a long story and it deserves a separated post. For now, just keep in mind that everything you make have to be and will be supported. You have to include this in your process of writing technical specifications.

If you fail to calculate support (or at least initial support) hours in your estimates you will end up stressed up and in problems.

Overall, the key to writing high quality technical specifications is to be clear, thorough, and organized. By following these recommendations, you can ensure that your technical specifications are accurate, complete, and easy to understand.

Conclusion

Let us make a long story short.

Writing technical specification is the least about technical stuff. It is about asking a questions. When you are writing technical specification you need to ask lots of questions, and then, ask some more.

You will be challenged with opposite opinions and this will happen constantly. People with opinions different then yours are not the enemies. They want to help you solve your issue but they see something you don’t see. How to deal with this? Ask some more questions. Try to understand them and their point of view.

Writing technical specifications is about gathering knowledge. Questions alone will not be sufficient. You need to learn. You have to know how to quickly learn new stuff, make prototypes, and apply them.

This article should be a motivation for you, a reminder that you need to communicate clearly.

And what about the estimates? Well, estimates and time-frames will come as a result of the answers and tennis match that you have with your team and product owners.

Time frames will not be something you just imagine from your head, when someone says “give me a rough estimate”.

The End