This article was originally written by Avanade alum Youenn Bouglouan

This is the second post of our mini-series dedicated to writing better specifications for your software product. If you haven’t done so just yet, you can find our first post here.

In this post I’ll address a seemingly innocuous question that might cause quite the controversy in your project if not addressed properly: who should write specs?

Let's state this right away:
No, programmers should NOT be the ones who write the specifications!

Why so? Well, the programmers are the consumers of the specs. Their job is to thoroughly review the requirements, spot and report any anomaly or inconsistency before proceeding to the implementation phase. They cannot do that if they wrote those requirements themselves. Also, as I’ll share in the next post of this series, a programmer's mind is often programmed (pun intended) in a certain way that makes it difficult for him or her to write specifications that are truthful to the business.

Now we know who shouldn't write the specifications. So, who should then? The clients or end users of the application? The project manager? The product owner? The business analyst? The answer, is all of them, together, to avoid what is described in the (in)famous drawing below:

Image credit: https://web.archive.org/web/20061018024303/http://weblog.cemper.com/a/200309/09-typical-project-life.php

Create a strong, diverse specs-writing team

Having end users take part in requirements-gathering sessions seems like a no-brainer. After all, those are the ones who will end up using your product and therefore should have a say in its making. In practice though, this is not always the case. The reasons are various: they sometimes don't have time for it, or worse, no one saw fit to ask for their opinion. Having higher management making uninformed decisions in place of their end users is a trap that a lot of organisations fall into. The risk is great here: in extreme cases the users might decide to boycott the product altogether because it either doesn’t answer their needs or even makes their work more complex than it used to be.

The business analyst is an obvious pick here. His role is to be the bridge between business and IT and to make sure both worlds get to understand each other. I'd argue that QA specialists, due to the very nature of their role, are an excellent fit here and should also be involved in gathering requirements. This has the following advantages:

• Engagement of the QA team early in the project (creation of test scenarios that programmers can use before the implementation phase starts).
• Avoiding situations where programmers must explain to their QA colleagues what the software should do, thus defeating the point of doing QA in the first place.

Bottom line: having a diversity of actors taking part in requirements-gathering is a good thing and naturally contributes to the creation of clear specifications. To sum up, having at least one end user, a business analyst and a QA specialist work together on the specs is a good idea.

Does it mean programmers should not be involved at all?

Absolutely not! While programmers should not write the specifications themselves, it can be very valuable to include their input early in the requirements-gathering process. This often helps prevent many IT catastrophes as listed in Part 1 of this blog post series:

• High technical debt due to the uninformed choice of technologies, languages, or frameworks to be used for the job.
• Failure to meet deadlines since what should have taken days, now takes weeks or months.
• Angry users and angry programmers due to the poor quality of the product.

What about your current project? Who is responsible for gathering and writing the requirements? What are the problems they are facing in doing so? Please share your stories and thoughts in the comments section below.

In the next and final post of this series, I’ll address the question: What should be included in the specs?

Thank you!

Youenn