Day 6: Write a Tech Spec

Hi, this is the sixth part of  a series of posts on 30 tips to becoming a better developer. If you would like to keep up to date with the topics that I am covering, just check the main post.

Among all practices that could make you a better developer, perhaps one of the most overlooked is writing tech specs.

In my opinion, the reason for this is that many feel that, since writing tech specs are not coding, so it must be boring and useless.

Boring it may even be, but useless it is certainly not. The time you spend to write a good Tech Spec can be the most useful hour of your whole development effort.

What is a Tech Spec?

A Tech Spec is the lingo used in software development for a document describing the technical features of a piece of software you want to write. Most of the time, tech specs are written in boring language — the kind of stuff that only a boss will read when creating another report.

It doesn’t need to be like this though. Although most Tech Specs are created using highly technical language, you can create your own tech specs in a language that is easy for you to understand. And, in fact, this is the way that I recommend that things be done.

Here are some tips that I try to follow when creating my own tech specs:

  • Create your tech spec at a level of detail that you are comfortable with. Add examples, pictures, sample code, whatever makes the concept easier for you to grasp. Don’t try to start with something formal and bureaucratic – it usually doesn’t work well.
  • If your boss requires a formal tech spec, create one from your original, personal spec. It will be easier to do, and after you get practice on doing this kind of things, it takes only a few minutes.
  • Append your original spec as supporting documentation. You want your fellow developers (or yourself, later) to have access to your original ideas, which are certainly easier to understand.

What If You Don’t Have The Time?

You certainly do have the time. This is one of the things where you will end up spending more time if you don’t write a tech spec. So, the issue is that you don’t have the time NOT to write a tech spec before coding. It is like building a house without a blueprint: you can do it, but you shouldn’t.

How Can I Learn to Do This?

It really takes some time and experience, but here are some tips that I think can help:

  • Write down all the functionality that you want to implement (a good functional spec might be required for this step — more about this later);
  • Describe how each functionality can be implemented: the classes used, major algorithms, and/or databases. Also, provide a high-level overview of the functionality that will be implemented.
  • Give some idea of the time necessary to implement the functionality. This is an additional step that will help you a lot in determining the scope of what can be done.


Writing tech specs is not easy, but it can become natural if you practice. Moreover, if you find out how this works it can save lots of time for your and your team. I highly recommend starting with simple specs for small functionality, and then extend this to more parts of the system. In the end, it is all about planning before executing.

Go to the next post of the series:

Similar Posts:

About the Author

Carlos Oliveira holds a PhD in Systems Engineering and Optimization from University of Florida. He works as a software engineer, with more than 10 years of experience in developing high performance, commercial and scientific applications in C++, Java, and Objective-C. His most Recent Book is Practical C++ Financial Programming.

3 Responses to “Day 6: Write a Tech Spec”

  1. It’s a very good article!

    By Alexander on Jun 23, 2009

  2. Thanks for this article. It gives me inspiration in my projects

    By erenNHun on Jun 24, 2009

  3. I think that writing Tech spec is a realy good practice, but I also think that is really important to spend some time to consider an higher abstraction layer.
    I found usefull to start thinking how people will interact with my system…something like a “use case”, this is more informal and I can use a completely informal language mixed up with sketch (or
    or whatever you prefer).
    So in my opinion the workflow should be:
    use case -> tech spech -> code (or test if you TDD)
    In this way you can gain specificity in small steps.
    By the way excellent series of articles

    By Luca Bernardi on Jul 3, 2009

Post a Comment