Help yourself and your programmers by writing better specs!

Hi, as promised in my last post where I wrote about the scary world of project failures in IT, I am back today to help you avoid getting yourself in a similar situation. How so? By giving you a few tips on how to write better specs! 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. As requirements are meant to convey the whole meaning of a project, this of course causes a lot of issues down the line.

In this post I will be freely using the term specifications, or simply specs, to refer to the document(s) handed over to the programmers so they can start implementing the Software. Now let’s try to answer the following questions:

  • What are the signs that you might have insufficient specs?
  • How should the specs look like?
  • Who should write specs?
  • What should the specs be about?

What are the signs that you might have insufficient specs?

Below is an non-exhaustive list of signs that may show that your project lack 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 actually 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 the 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 in the past, you might find some valuable information down there.

How should the specs look like?

I believe most of us have played at least once in their life the popular game called Chinese Whispers. 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 photos of your dogs while they lick the pastor‘, 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 Alexandro, what’s the best format to write specs then?‘. This is my very personal opinion, but I believe that you should favor wiki-based specs over office-like documents, for the following reasons:

  • We all know the pain of sharing documents with 10 other people over email and exploding everyone’s mailbox quota.
  • 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.
  • We all lost our sanity while editing a Word document in review mode, so full of red squiggles and comments that we needed a ultra-wide monitor to display it all.
  • We despise SharePoint from the bottom of our soul.

At work I am currently using (and abusing) Atlassian Confluence, which in addition to being super intuitive and ergonomic, allows 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 thing you’ll do in your life, so make sure you have all the proper tools at hand to make your job easier. But whose job it is anyway? Let’s discuss it.

Who should write specs?

Let’s state this right away so it is clear for everyone:

No, programmers should NOT be the ones writing the specifications!

Why so? Well, the programmers are the consumers of the specs. Their job is to thoroughly review the specs and find potential anomalies or inconsistencies in them before heading to the implementation part. They cannot do that if them wrote them themselves. Also, as we will see below, a programmer’s mind is programmed (pun intended) in a certain way that makes it difficult for him to write specifications that are truthful to the business.

So we now know who shouldn’t write the specifications. But 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 famous drawing below:

Having end users take part in capturing requirements seems like a no-brainer. After all, those are the ones the Software will be written for 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 actually saw fit to ask for their opinion.

The business analyst should also be a clear pick here, as he often is the bridge between business and IT, being able to understand both worlds. I’d argue that QA specialists, due to the very nature of their role, should also be involved in preparing specifications. This would bring the positive side effects:

  • Engagement of QA early in the project.
  • Avoiding situations where programmers have to explain to the QA peeps what the Software should do, thus defeating the point of doing QA in the first place.

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

What should the specs be about?

Good specifications should ideally contain enough information so none of the questions the programmers typically ask are left unanswered. What do programmers typically ask about? Let’s try to put ourselves in the shoes (and mind) of a programmer. Beware, sensitive souls refrain!

I wrote down a simple pitch of an application to serve as an example. Let’s give the application an original and catchy name: PizzaManager. Here it the pitch:

This new application will help our Italian restaurants manage our large choice of pizzas in an intuitive manner. The main screen should allow users to:

  • Display the list of pizzas available on the menu.
  • Add new pizzas to the menu.
  • Edit existing pizzas.
  • Remove pizzas from the menu.

Yipee! We might think that this is enough to get development starting, but this is very far from the reality. Below is a non-exhaustive list of questions your programmers will sooner than later have to answer when they go down the development road.

Hardware / platform requirements:

  • Does it have to be a desktop client? A website? a mobile application?
  • What OS should it run on? What is the hardware available in the restaurants?
  • Is touchscreen support needed?
  • Where should the data be stored? On a private centralized server? In the cloud? On the local machine? How will handle backups?
  • Will the DEV team have access to a realistic test environment?

Performance concerns:

  • How many users can be logged in at the same time?
  • How many pizzas should the application be able to handle?
  • How many actions per second/hour/day/month should the system process?
  • What are the expected response times from the system for each given action?

User Interface design:

  • How should the pizzas be displayed? In a grid or in a list? Maybe both?
  • How many attributes (size, price, name, ingredients, …) should be displayed?
  • How many pizzas should be displayed simultaneously on the screen?
  • Are advanced UI functionalities required (responsive design, drag&drop…)?
  • Should users be able to sort or filter the list of pizzas?
  • Can the user interface be customized?
  • Should the screen display pictures of the pizzas too?

Business requirements:

  • How can users log in to the system? Via password, smart card, badge, fingerprint…?
  • Can users be assigned roles and permissions, e.g. standard user versus administrator?
  • What are the validation rules to apply to a pizza?
  • Should the application be available in several languages?
  • Is an integration with the main website or any external system planned in the future?
  • Can users edit several pizzas at once?
  • Can users create a new pizza by copying an existing one?
  • Can users delete several pizzas at once?
  • Can there be two identical pizzas in the list under different names?
  • Should there be an additional prompt message displayed when deleting a pizza?
  • Is there any need for auditing capabilities (who created / edited / deleted pizzas…)? What is the expected granularity?


(This one is often omitted during requirements gathering. I spent 18 months working exclusively on a data migration for a single medium-size project, so I can tell you this is not something you should take lightly!)

  • Who is going to prepare the data for the migration?
  • What are the differences in terms of data format between both systems?
  • Who is going to run the actual migration from the old system to the new one?
  • How will the migration be done? Database migration, manual insertion, custom interface and logic…?

We have around 30 questions already,each of those having a significant impact on the end product! The answers to all those should figure somewhere in the specs. Otherwise, the following can (and will) happen:

  • Programmers will realize that a big breaking change is required right in the middle of the implementation, because they did not foresee one specific case. This will introduce delays and technical debt in the project.
  • Programmers will make decisions driven by the technologies (the languages, databases or frameworks being used) to compensate for the lack of guidance that should have been provided by the specifications.

As you can see, programmers have many things to account for, and adding unclear business requirements to the balance might very well bring the project to his knees. Fortunately, you, as a specifications writer, can reuse the below collection of must-have items to ensure that your specs at least answer a minimum number of those concerns.

Explain the context

It is very important to set the context and scope of a project straight from the beginning. The initial pitch mentions Italian restaurants (plural). How many of them are those? 3 or 300? Will the application be used in each of them? Gather the information and put it at the beginning of the specifications.

Is the new PizzaManager application going to replace an existing system? If yes, what were the advantages and drawbacks of the old system? When is it going to be replaced? Why did they want to go with a new system? Answering all those questions on paper will help you identify a lot of hidden problems (read, hidden costs) and come up with appropriate solutions.

Similarly, you must define who your team will be working with: does the client have his own IT or DEV team? Are they responsible for some of the project deliverables? Will your programmers have to interact with them in any manner?Identifying all the actors within the project is crucial, so as usual, gather the answers and write them down in the specs.

Explain the domain

The application pitch is full of nouns that you must explain in great detail. For instance, the concept of menu seems pretty blurry and should be clearly defined: The menu refers to the whole list of pizzas currently available for sale within the application. It is not related with the physical menus handed out to clients of the restaurant.

The same applies to users. Define who will be using the application and what will be their role:

  • Managers can delete pizzas and change their prices.
  • Waiters can create and edit pizzas. They cannot change their prices.
  • Pizzaiolos can only browse the list of pizzas and see their main ingredients.

The pitch also contains several verbs, like manage, add, edit, remove, display… You must as well define what those verbs mean, for instance:

  • Removing a pizza will permanently delete the entry from the database.
  • Removing a pizza will only make it disappear from the main list of pizzas on sale. It can be added back later on by a manager.

Define a list of immutable business rules

In any application, there are cornerstones that prevent all hell from breaking loose on the poor users. The specifications should explicitly state those immutable business rules on which the Software relies. In the context of PizzaManager, it could be:

  • Only managers can remove pizzas from the system.
  • The system should not allow to remove the top 5 best-selling pizzas.
  • A pizza should never contain both pineapple and broccoli at the same time!

Those rules will allow your programmers to build the Software on stable foundations. Rules are usually easy to reason about and will bring sanity back in your DEV team.

Describe in details all business scenarios

All actions available to the users should be listed and described in details. The pitch mentions the following scenario: Add new pizzas to the menu. This is way too vague and your programmers will surely come to you and ask multiple questions about it. You can avoid that by explicitly stating what the action is meant to do:

  • Log in the application and navigate to the main screen.
  • Click on the Add button in the ribbon. The pizza creator wizard will appear as a popup.
  • Choose the list of ingredients the pizza will be composed of.
  • Click on the Create button at the bottom of the wizard.
  • The pizza you created will now appear on the main screen.

Writing down those scenarios will also help you verify that your immutable rules actually make sense! Additionally, there are a great starting point for your QA specialists.

But do not stop at the happy path!

The scenario we described below only goes through the happy path. However in real life users may encounter issues from different natures while using the application. Those issues also need to be addressed in the specifications. For instance:

  • After you clicked on the Create button, an error message will be displayed if the pizza already exists in the system: ‘Another pizza with similar ingredients already exists in the system. Duplicates are not allowed.’
  • If the connection to the main server was lost while creating the new pizza, the data should be stored locally until the connection is back.
  • If you are currently editing a pizza that was removed from the system in the meantime, a notification should be displayed at the top of the screen: ‘the pizza you are editing does not exist anymore’.

The general idea is to not let any element left to improvisation. Errors and failures will happen, so they should be taken into account in the specifications.

Define metrics up front

Last but not least, having an idea of how a system is expected to react is vital in order to properly choose the proper architecture and technologies for the job. Define those expectations in the specs as well:

  • Users are expected to create between 100 and 250 new pizzas per day.
  • Around 40 users will be simultaneously logged in in the system at all times.
  • Loading the the whole list of pizzas in  the user interface should take more than 2 seconds.
  • A pizza created in 1 restaurant should be available in the other 30+ restaurants after 1 minute at max.
  • Data should be backed up 4 times a day.

If you see metrics like those, you will know that what you are expected to build is not just another simple restaurant manager but in fact a complex piece of software with thousands of entities, near real-time synchronization between shops and a few dozen concurrent users logged in.

Let’s wrap up!

That’s it for today. I hope I helped you understand why gathering requirements is such a vital part of Software development. Writing clear, complete and consistent specifications is not an easy job but the success of your project largely depends on it. Hopefully the ideas and concepts above will help you get started. Happy writing!


7 thoughts on “Help yourself and your programmers by writing better specs!

  1. Pingback: “Oh no, why is my software broken again?” A scary IT story – Youenn Bouglouan

  2. Dawid

    I totally agree with your opinion on maintaining specs. However, I’d wish myself and everyone that each company has analysts, PMs and Customers with technical knowledge enough to think about the projects on such levels, to be able to ask themselves kind of questions you proposed. Maybe that’s the problem in many cases, that “business” people, PMs and all people connecting development teams with business have no technical background ? Or their technical consciousness is on too low level for maintaining IT projects ?

  3. Youenn Post author

    I believe a lot of factors come into play here. The one that you mentioned, the lack of “technical awareness”, is definitely one of them. However I don’t think this is the most problematic one. If you look at the list of questions above, you’ll find that very few of them are actual technical questions. For instance, the people writing the specifications do not need to know the difference between MySQL and MongoDB. It is better if they do, but that is not absolutely necessary. What they need to do though is ask the correct questions: what is the current daily traffic on your website? What are your expectations for the next month? How often do you want to get the updated sales report? The goal is to gather enough information so the programmers have a chance to make an informed decision and pick the correct tech accordingly.

    The main causes of the problem are in my opinion a bit different:
    – lack of communication and ownership of the people writing the specifications. They “pass the baby” to the programmers who get blamed because “they are the ones who didn’t understand the specifications!”.
    – dishonesty toward the client. “Let’s lie to them about our actual capabilities by writing vague specifications so they sign the contract and we can all get our bonuses”.
    – lack of education and support from the management. If they gave bonuses for writing complete, consistent specifications, I am pretty damn sure people would put more effort into it. I guess we could make a parallel with Conway’s law here, that says “Any organization that designs a system will inevitably produce a design whose structure is a copy of the organization’s communication structure.” So basically, there is a chance that the specifications will reflect the culture of the organization :).

    I hope it partly answers your questions, let me know if you have another take on the subject :).

  4. Dawid

    Thanks for this comprehensive answer. I have however one more query on this topic: you state that programmers shouldn’t write the documentation. What about the technical dosc? Assuming you don’t do TDD where tests might be considered as well enough technical documentation. Should it be written at all and if yes, by who?

    1. Youenn Post author

      Just to be clear, I stated that programmers shouldn’t be the ones write the specifications. If it comes to technical documentation however, then yes, the programmers should write it. Actually, they are probably the only ones with the skills to do so. They could also participate in writing user documentation, although it’s probably better if someone else can do this so the programmers can focus on what they’re paid to do – writing Software :).

      In the post I also mentioned that “Good specifications often translate into good documentation”. Specifications define what the Software should do. Documentation defines what the Software does. If the programmers did there job correctly, the two should end up being pretty similar :).

  5. Pingback: Programmers want to have fun, too! – Youenn Bouglouan

  6. Pingback: Putting together the Software Dream-Team – Youenn Bouglouan

Leave a Reply

Your email address will not be published. Required fields are marked *