However, it is easy to make a specification but it is hard to make it clear enough to let the development team know what to be done;
Here is some tips to help you make a better specification!
Tip #1: Think about the audiences
To make a good specification, it is important know who are you audience;
Different kinds of audience have different needs and common needs;
As mentioned before, the basic need is that the specification can help them work;
Beside it should be easy to read because the readers won’t be have much time to study your specification; It is not possible that your readers will spend an hour to study the specification in order to kick start their works.
- Here are different audiences of the specifications and their needs:
- Project Manager: They use the specification to estimate the time and cost.
- Coder: They use the specification to design the system and also implement the behaviours of the system.
- Artist: The specification should tell them what to be created or the format of graphics they need to product.
- QA/Tester: They use the specification to derive the test cases and a reference to judge the system is doing right or wrong.
Tip #2: Using Bullets, Tables, Diagrams and Images
As said before, specification need to clear and easy to read; Thus, we cannot write the specification like what we write a novel, blog, … ;
To help your readers get the information quickly, we can the following items:
Bullet Form (Point form) is a very good way to list our your ideas; I usually use bullets to list our the objectives and work breakdown of the feature to be developed.
Table is a tool to tell structure information like an object properties, cases;
Here is an example from Android:
They use table to tell which words to be avoid and how to correct them:
Diagram is another tool to organise information and help programmer easier to write their code; There are many kind of diagrams that help presenting the information;
Here are some famous:
Flowchart – Tell the flow or logic of your idea
Sequence Diagram – Tell different entities interact with others. e.g Client/Sever
Here is an example from Apple:
They use flowchart to tell how to handle an notification in the Apple Watch;
It is true that Picture can tell a thousand word;
Without a picture, developer may mis-understand what you need and code something wrongly; It usually happened in UI development;
So try to add more pictures to tell the requirements that related to visual things;
Here is an example from Android:
They use an image to tell the changes of notification after expanded;
Tip #3: Peer Review the specification
Unless you are a very experienced specification writer, you cannot make a specification that help everybody using just one version;
I think it is not possible even to the experienced writers.
In my past experience, having peer review, many useful information were added.
Here are some cases:
Missing considerations about a function;
Lack of information such as what the UI should be;
If you are a product designer with no technical background or art ability, try to find a technical guy and an artist to help you;
In software development, the communication is one of the important thing; If the communication is poor such as incomplete specification, it cause a lot of information loss from your idea to your product;
I usually tell many colleagues to write down the good points they mentioned to prevent the point being lost in future;
In short, spend EFFORT to make a good specification for your team;