3 Tips to make a good Requirement Specification

In my ongoing and past projects, I always need work with the product designers or game designers; To make sure the artists and programmers can make the product, I always asked them to provide specifications;

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:

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.

Here is an example from Twitter:
twitter-example

Source: https://support.twitter.com/articles/117063-blocking-users-on-twitter

Tables:

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:

android-example1

Source:
http://developer.android.com/design/style/writing.html

Diagrams:

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;

apple-example
Source: https://developer.apple.com/library/ios/documentation/General/Conceptual/WatchKitProgrammingGuide/CustomzingthePushNotificationInterface.html#//apple_ref/doc/uid/TP40014969-CH6-SW1

Picture:

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;
android-example2
Source:
http://developer.android.com/design/patterns/notifications.html

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;
Contradictory Specification;
Lack of information such as what the UI should be;
Miss-spelled words

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;

Conclusion:

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;

Advertisements

2 thoughts on “3 Tips to make a good Requirement Specification

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s