How to write useful technical specs

I might be not that wrong in assuming that a lot of IT people out there encounter same problems regarding tech specs all the time – they become obsolete sooner than they are written. Mostly created to show the client – hey, we’re doing stuff here, here is the result, 100 pages of pure informational power. However, the result is often the same – after one glance, each team member will soon forget that this spec ever existed.

So how make specs more useful? In this article I won’t show how to formulate your spec, but more how (technically) to manage, that your spec stays up to date.

Use LaTeX

No, not in the bedroom with your girlfriend (on the other side – who am I to judge you?), but the document markup language (according to Wikipedia).

LaTeX is not only cool – writing specs feels almost like writing code – but it allows you to maintain a healthy development process considering your spec.

Problem No. 1

When your specs are starting to get bigger and you add stuff here and there, it is very (VERY!) hard for your team to follow up on changes. Using GIT in combination with LaTeX allows you to commit any changes just if it were code. And GIT markup fantastically highlights all changes that were made. So next time you can just give your team a link to the latest commit to they will see only the new and recent parts.

Problem No. 2

Have you ever tried to create links within a document, say in MS Word? Yeah, you kinda able to do that, but if you add, say, a new point to your numerical list, all your links will get messed up. Regardless to say what happens if you add a whole new chapter at the beginning. LaTeX allows you to define variables, just like any programming language. Just use a simple

where section:intro is just a clear variable meaning that your content is in the section called “intro”.

Problem No. 3

As soon as you try to maintain your MS Word spec you realize how this program is clearly not created to write large documents. Ever tried to create a numerical list, then add a break and continue the list? Then you’ll know how easy it is to screw things up. By being completely controllable there is always an easy solution for almost everything you want to achieve with a LaTeX document.

Use GIT

I mentioned it already in the previous paragraph, but I can’t stress it out enough – your LaTeX spec will really shine bundled with GIT. Not only you have a neat version control (and don’t need to save “project_x_tech_spec.v.1.0.docx”, “project_x_tech_spec.v.1.8.docx” and so on), an ability to link only your recent changes by sending a commit link, but you also have one place for your always up-to-date end format, because recently github learned how to display pdf-files.

So basically your pdf url stays always the same, something like this:

https://github.com/username/docs_folder/blob/master/your_project/spec.pdf

My setup

Since TeX is permissive free software (to me it sounds a lot like open source), there is a bunch of good free editors (honestly, even notepad will do it). However I felt in love with Texpad – it’s available only for MacOS (and iOS) and makes full usage of your retina display. It costs 25 $ and is available for download at Texpad homepage.

Starting writing documents with TeX may be a bit hard the very first time (on the other hand – what isn’t hard the very first time?), but there are plenty amount of templates out there on the interwebs helping your out to fire your document up. My personal favorite (there are few Russian language related things which you might omit) :

Happy writing!

Published by

Anton

Hello! My name is Anton. I am a passionate project manager who loves digging deep into code. You can check my Github and CodeEval. Hopefully my thoughts on management can lead you to one or another good idea.