This article was originally written by Avanade alum Youenn Bouglouan

This is the third and last post of our mini-series dedicated to writing better specifications for your software product. If you haven’t done so just yet, please check out the first and second post of the series.

These two previous posts answered the following questions:

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

Now it is time to answer our last and probably most important question: What should the specs be about?

Good specifications should ideally contain enough information so none of the questions the programmers might typically ask during the implementation phase 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 application pitch that will serve as an example for this post. 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:

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

Let’s roll! We might think that this is enough to start development, but this is very far from the reality. Below is a non-exhaustive list of questions your programmers will have to answer sooner than later 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 hardware is 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?

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, etc.) should be displayed?
• 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?
• Should there be an additional prompt message displayed when deleting a pizza?
• Is there any need for auditing capabilities (who created / edited / deleted pizzas)?

Data migration:

(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!)

• 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?

Programmers usually have a lot on their plate already and adding unclear business requirements to the balance might very well bring the project to its knees. Fortunately, you, as a specifications writer, can reuse the below collection of must-have items to ensure that your specs answer at least 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). But how many exactly? 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? 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.

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 to 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 includes verbs like manage, add, edit, remove, display. Define what those verbs mean. For instance, remove might convey either of the following:

• 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 by a manager.

Define a list of immutable business rules

Applications often have a set of business rules that should apply no matter what. The specifications should explicitly state those immutables. In the context of PizzaManager, those 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 product on stable foundations and make sane technical assumptions.

Describe all business scenarios in detail

All actions available to the users should be listed and described in detail. The pitch mentions the following scenario: Add new pizzas to the menu. This is too vague and will raise a multitude of questions. Instead, state what the action is meant to do:

• Log in to the application and navigate to the main screen.
• Click on the Add button in the ribbon to display the pizza creation wizard.
• Choose the list of ingredients that will be used to make the pizza.
• 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 above only goes through the happy or “ideal” path. In real life however, users may encounter several issues while using the application. Those issues must 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.

Define metrics up front

Finally, set proper expectations for the performance of the application. This will allow the team to pick the appropriate architecture and technologies for the project. For instance:

• 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 up the whole list of pizzas should not take more than 2 seconds.
• A pizza created in 1 restaurant should be available in the other 30+ restaurants after 1 minute at max.

Such metrics will help you assess what you are expected to build: is it just another restaurant manager, or is it a complex piece of software with thousands of entities, near real-time synchronization between shops and a few dozen concurrent users logged in?

Final words

This wraps up my mini-series on how to write better specifications. I hope this 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.

Have any questions or remarks on the topic? Please share with us in the comments section below!

Thank you,

Youenn