The art of writing Software Specifications

• Don’t use two names for one thing or one name for two different things.

This will reduce the changes that bad interpretations can happen. When you write specifications is not the time to show your vast vocabulary.

• Write short sentences.

Be direct and short. Short sentence have more chance to be understood in a total than very long elaborated ones.

• Divide by topics.

When a specification has more than one statement just divided them by topics.

For example:

When the follow conditions are assured:

Bla bla bla,

Bla bla bla,

Then shall the software…  blab la bla

Avoid writing in the passive form.

Always describe who is responsible to perform an action.

• Images and diagrams.

These are an excellent help to describe better a requirement and what is asked in it. But images and diagrams can never be by themselves requirements; they are used to complement and not to substitute.

• Justify always the existence of the requirement.

You may already know why you have to do that requirement but the new guy that is going to join the team don’t. It’s always good to document at a good level everything. (Should I justify that?)

• Never write a solution in a requirement.

• Write only requirements that can be tested.

We can’t test requirements that need to happen “very fast” or “ in the next minutes”.

• The requirements need to be numbered.

• Zero redundancy tolerance.