This article was originally written by Avanade alum Youenn Bouglouan

Welcome to the first post in this mini-series dedicated to writing better specifications for your software product. Being able to capture requirements that are clear for both business and IT is a vital part of any software project, yet I feel this part is often overlooked.

Because requirements are meant to convey the whole meaning of a project, not having proper specifications causes a lot of issues down the road. Some of these include wasting your team's time and wasting your client's money.

In these posts I will use the term specifications, or simply “specs”, to refer to the document(s) handed over to the programmers so they can start implementing the software. By the end of the series we'll be able to answer the following questions:

• What signals indicate that you might have insufficient specs?
• What should the specs look like?
• Who should write the specs?
• What should the specs be about?

What signals indicate that you might have insufficient specs?
Below is a non-exhaustive list of signs that may show that your project lacks consistent and accurate specs:

• High technical debt. Technical debt can be born from inaccurate specs that lead programmers to implement things they do not fully understand or are not necessary, thus introducing additional complexity.
• Missing or incomplete documentation. Good specifications often translate into good documentation as they should reflect precisely what the software does.
• Failure to meet deadlines. You cannot expect programmers to implement a program in a timely fashion if you are not able to explain in plain English what said program should do or not do.
• Angry users and angry programmers. The former complain because the software does not do what it is supposed to (or does it in a very unintuitive and inefficient way). The latter complain because they were not given a fair chance to do good work.

If you experienced any of those problems in the past, you might find some valuable information in this blog mini-series.

What should the specs look like?
I believe most of us have played at least once in their life the popular children’s game called “telephone”. If not, I highly recommend you do so. It can be a lot of fun while teaching a very valuable lesson:

We humans often fail at communicating in an accurate and effective fashion.

This is even more true while using verbal communication. What's the point of all this? Well, if you don't want your application which 'helps seniors share pictures of their pets in one click' to turn into a program that 'takes pictures of the pastors when they're sick', then you'd better put those specifications on paper! Having written specifications is mandatory if you don't want any important piece of information to be forgotten, lost, or even worse, misinterpreted.

'So Youenn, what's the best format to write specs, then?' I recommend wiki-based specs over office-like documents, for the following reasons:

• Overwhelming emails. We all know the pain of sharing documents with 10 other people over email and exploding everyone's mailbox quota.
• Overlapping efforts. There were always moments when Jessica made modifications to final_specifications_january_v4-5-31_final_bis_draft1.docx while Gregory was already working for a few days on specifications_january_v4-5-37_lastest_final_bis_bis_2.docx.
• Over-editing madness. We all lost our sanity while editing a Word document in review mode, so full of red squiggles and comments that we needed an ultra-wide monitor to display it all.

I’d recommend using tools that are intuitive, ergonomic and allow you to:

• easily share your specs by sending an URL
• quickly compare changes thanks to the built-in version control system
• comment and collaborate on the same document in near-real time

It is so easy to use that you might even start to like writing documentation! Writing specs is not going to be the sexiest task, so make sure you have all the proper tools at hand to make your job easier. But whose job it is anyway? Well this is the main topic of our next post: Who should write the specs?

Thank you and see you in the next post!

Youenn