How to write a good IT product specification?

It is obvious that a lot of mistakes on a computer project or failures, are due to incomplete product specifications, as they may not be clear enough or properly structured. 
Here is a list of good practices to respect in order to minimize misunderstandings and misinterpretations, in terms of the specifications that seem to jeopardize a web product. Writing a specification for a computer software is taking the time to jot things down clearly and precisely, right from the beginning.

1. Choose the right document template

It is necessary that you select the right functional or technical template as for the specifications. A good template should include at least one cover page, a summary, headers for each new section, titles, subtitles etc. but also a brief introduction which presents the overall goal of the IT system. The document must also include a version number and a table which tracks down the changes, made in the document, with the corresponding version numbers.

2. Plan out a hierarchical structure

To provide an easy-to-use document in its entirety, structure your specifications. The structure can include a part about the supplier, one on the client, one on the task etc. Depending on the amount of information which is provided, do not hesitate to integrate sub-levels. This will help you define the scope which has been covered by your specifications.

This type of information layout will help you focus on the specific area, that needs to be addressed and therefore write down the functional requirements in these documents, make them as precise and complete as possible…

This will also allow you to highlight areas, which you will need to modify or areas where you need to pay attention. Most companies will articulate their document around system levels depending on the nature of their business. In case the document describes a functional structure, the very broad missions will be defined right at the top, then they will be broken down into subfunctions, then its own sub-functions will be divided into tasks.

3. Use unique identifiers

This may be surprising, but many documents don’t have a system for identifying functional requirements. Generally speaking, when a system is ordered between a customer and a supplier (as in most government-controlled systems, for example) these systems are developed according to certain standards and these standards require for each required document to be marked as a unique project identifier (UPI).

Why does one need to have a unique identifier linked to the hierarchical structure of your specifications? There is a very good reason for this, marking each requirement with a unique identifier, improves and simplifies traceability between high-level requirements and low-level requirements. The identifiers make the creation of a traceability chart easy and thus clearly list out the requirements related to the important documents, but also the specific tests which intend to check these requirements. Traceability charts simplify the demonstration process with the client and project stakeholders. The tracking of the developments and the delivery of the finished functionalities is more easily traceable, and this type of document proves that the deliveries are in keeping with the requirements, defined in the highest levels of the document.

Link the unique identifiers of the requirements, to the paragraphs of your specifications, this will help users find them more easily in the document. The specifications that do not use this type of coding are difficult to read and consult and therefore make traceability laborious.

Example of a hierarchy of functional requirements with sub-paragraphs:

3. Management of subscriber account information

3.1 Updating subscriber account information

3.1.1 Synchronization of a subscriber account with CRM

3.2 Deleting a subscriber account

3.2.1 Synchronization with associated CRM and PDV

3.2.2 Updating billing status

4. Standardizing the vocabulary which is used

Like most languages, French is a language which contains words that have subtle nuances of meaning. To prevent each person from analyzing a sentence in their own way, and to avoid confusion and issues, it is important to specify and define the vocabulary and concepts that shall be used.

Defining the vocabulary, helps to tell the reader how such and such term should be analyzed, when it is discovered in the document.

5. Make sure each requirement can be tested out

Each requirement is assigned to a unique project identifier. Thanks to this unique identifier, it shall allow the requirement, to support testing and traceability. The test’s aim must be precisely described, so that the requirement can achieve it.


Why should one do that? To ensure that the developed functionality will properly respond to the requested requirement. Whenever you describe a requirement, you must ask yourself, “How can I meet this requirement?” So, you write down a test scenario for each requirement, which proves that the requirement is testable. By structuring your application depending on the specific test scenario, you are ensuring that design engineers understand what they need to do, in a precise manner.

6. Write down functional requirements which need to be realized in a neutral manner.

Write functional requirements in a neutral manner, this way you don’t restrict the software design engineers and allow them to design the system in the most efficient manner possible. Indicate what system should be used, not how it should be used. The constraints related to the implementation must not appear in the functional requirements.

Avoid using the passive voice: instead of saying “The canceled subscription will be updated in the sales department”, favor saying “If the subscription is terminated, then a subscription termination notification, shall be sent to the sales department”.

7. Don’t hesitate contextualizing requests

The more the request is specified by a context, more it will make sense and shall be understood by the design engineers. Highlight the business aspect of the requirement (example: when a subscriber terminates his subscription, it is necessary that the sales team is notified so that the latter doesn’t offer the product anymore to the subscriber).

Make sure you separate the requirement from its justification, make this separation very clear.

8. Use a common requirement writing format for all requirements

To make the requirements clear and functional, use a common sentence construction between all functional requirements, use attributes common to all requirements.

Example:

ID: 1.1.2

Object: Canceling a subscription

Action: When a subscription is terminated, a message is sent to the sales team, alerting them on this termination.

Condition: If the subscription is terminated by the subscriber since at least 14 days.

9. Identify all the possible scenarios (identify exceptions)

To cover all usage cases of a requirement, list out any exceptions that may occur. This makes it possible, to avoid forgetting cases which haven’t been considered or possible impacts that certain cases might have on other requirements.

Example: 12 days after having canceled his subscription, the subscriber changes his mind and no longer wishes to terminate it, you must reactivate his subscription. Other news on outsourcing IT projects.

IT offshore, specialized provider of software development, we accompany you and advise you in terms of writing of your specifications. We have strong expertise in software developing, proven through more than 120 projects.

Source: qracorp.com