Help yourself and your programmers by writing better specs!

#blog #dajsiepoznac #dsp #software-dev #requirements #specs

Forenotes from 2023

This post was originally published on my blog on April 1st, 2017. If I'm not mistaken that was the longest post in my Daj Się Poznać 2017 blog post series 🖋️! As for Putting together the Software Dream-Team, re-reading this 6 years after made me giggle at times 😃. For instance, the mention to Atlassian Confluence being great didn't age super well (it still does the job, but now feels a bit dated in comparison to other competitors). It feels like I was making shortcuts in some aspects when I originally wrote this piece, and were I to write that same post again today, I would probably try to be more nuanced. The piece gave a rigid, waterfall'ish vibe at times, and it was clearly not my intent. I still find all the examples of questions you may ask relevant though. Asking and answering as many questions as possible in writing is always a good use of your time. This was not a buzzword back then, but maybe this would be branded as Product Discovery™️ nowadays. Fun fact: I also had the opportunity to publish again some of my posts on the official blog post of my former employer. I had completely forgotten about these, but you can still find them here, here, and here! Them being a big corporation, I had to rewrite parts of the post to be compliant. For instance, any mention to ethnicities like "Chinese Whispers" had to be removed. Also, who knew it's not OK to mention Sharepoint is bad and strongly disliked when you work indirectly for Microsoft 😅?

Help yourself and your programmers by writing better specs!

Hi, as promised in Oh no, why is my software broken again? - A scary IT story, 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?

Below is an non-exhaustive list of signs that may show that your project lack consistent and accurate specs:

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 that '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 favour wiki-based specs over office-like documents, for the following reasons:

At work I am currently using (and abusing) Atlassian Confluence, which in addition to being super intuitive and ergonomic, allows you to:

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:

requirements.jpg

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:

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!

programmer_mind_opt.gif

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 is 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:

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:
Performance concerns:
User Interface design:
Business requirements:
Migration:

(This one is often omitted during requirements gathering. I once 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!)

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:

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. 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:

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

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:

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:

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:

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:

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 synchronisation 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!

Cheers