Helper Guidelines

Users don't know what they want until you show it to them

Focus and Clarity

Focus is the most import aspect of any requirements document. A good requirements document clearly states the objective of the project and defines its scope, to clarify what the project does and does not cover.

A Format for Specifying Requirements

Discussing the many ways in which requirements can be gathered can end up in a heated and impractical debate. The short answer is that you should gather requirements using whichever method works for you, the most important outcome is that the people who need to understand the requirements can do so. If the people that form the project team (client, stakeholders, designers, developers) are happy with the format, that's half the battle won.

This is not to say that all formats of requirements documentation are equal. If you happen to believe that use cases are effective, but your client doesn't understand UML, then it's going to be difficult for them to effectively review the document and identify any errors. This increases the risk of misinterpretation. If the document is too technical, the client is likely to assume it's correct because they don't really know otherwise. These sorts of assumptions don't surface until the work is done, at which point it becomes far more expense to fix. This scenario brings us back to the purpose of a requirements document: to avoid these mistakes in the first place.

So, if you have a format that you, your client and your project team are comfortable with, stick to it.

The Author of the Requirements Document

The art of writing requirements takes great skill and, like writing code, the end result is usually cleaner and more consistent if there's a single author. Great care should be taken in selecting the author. It's a matter of balancing the need for a thorough understanding of the project domain (i.e. the client's business) against understanding the process of software development. An author with a great understanding of the project domain but no experience with software development is a risky choice. So is an author with no understanding of the project domain but extensive experience in software development. Ideally, you want to aim for an author that has both.

The Language of Requirements

If there's only one rule in the use of language then it's to use the same language as your client. It's that simple. If the language is consistent, it greatly lowers the risk of misinterpretation of the requirements. For example, a recent project contains a product catalogue for seeds. In the first draft we categorized the seeds into 'types', 'categories' and 'sub-categories'. While this made sense to us, the client and other stakeholders use the terms 'crop', 'type' and 'variety'. This was bound to cause problems if we didn't use the same terms as the client. A useful technique to avoid this problem is to include a glossary of terms and definitions in the requirements document.

Accuracy is Critical

There's little use writing requirements if they are not an accurate reflection of what the client wants. We've found the best way to deal with this is to walk the client through the requirements, as they'll rarely read them on their own. If it takes five reviews to get it right, then so be it. While it can become a drain to do multiple reviews, persistence pays off. Remember: it costs many times more to fix things in testing than in the requirements phase.

Having said that, don't expect to get the requirements 100% correct. You need to allow for human nature. A requirements document is a statement of 'what' the end result has to achieve. Even with the best intentions in the world, sometimes when we arrive at the end result, it just doesn't work the way we expected -- it's a fact of life. So, the requirements should capture what the client wants, but allow for change as long as the objectives are still being met.

Minimize the Risk of Errant Interpretation

Being clear and unambiguous is difficult. In law, there are rules for interpretation, but even then, those rules are applied by judges who have their own interpretations of how to apply the rules. What does that mean for requirements? It's important to ensure everyone has the same understanding. One of the best ways to minimize the risk of different interpretations is to include examples: diagrams, pictures, or sample data that illustrates what the requirements mean.

Best Practices

Don’t give me best practices, they are yesterday’s news.

Give me emerging practices, they are tomorrow’s news.

What “Requirements Gathering” is all about is info transferring and sharing. The “Requirements” document can be considered as the real project contract between the user and the developer, and it is also the first draft of the project plan.

In brief:

The Requirements Document is
the Business coded version of
the User’s Specifications written using
the Human Programming Language!

To approach this description, there are some advised best practices to make sure that the user’s business requirements will be smoothly translated into the “required” program. Among these best practices are some suggested tips to be taken into consideration while producing the requirements artifact be it a document, a prototype, a list of features… using the aid of whichever techniques of the previously mentioned ones.

The requirements should include the following:

Approvals

The “Approvals” section is the first step determining stakeholders even if they don’t participate in the requirements gathering exercise. Approvals list includes the stakeholders names, their titles and their signatures.

Objectives

The “Objectives” section also known as the “Problem Statement” section gives the reader of the document a brief idea about the purpose of the project and the needed system. It gives an overview about the system and may describe the background of the problem and the impact of implementing the requirements.

Scope

The “Scope” section clearly states what should be covered by the proposed solution and what will not covered. It determines the “In Scope” and “Out of Scope” requirements.

Business Goals

The “Business Goals” section helps developer and business stakeholders understanding the goal of the project and sharing the same view.

Assumptions

As requirements gathering and analysis is an intermediate step between the business requirements and the to-be developed system, it is very important to ensure that all stakeholders and developers have a common understanding. As humans, this is almost impossible to achieve, at which point the importance of the “Assumptions” section emerges, it helps all stakeholders viewing, as much as possible, the requirements from the same viewpoint. Assumptions may include business, technical and planning assumptions.

Constraints & Risks

The “Constraints & Risks” section helps identifying problems facing the product implementation at early stages, thus facilitating decision making and project planning. Constraints and risks may be business and/or technical.

Pre-requisites

In the “Pre-requisites” section you can define any dependencies the project will be rely on and will not be launched unless they exist.

References

The “References” section refers to other helper systems or documentation.

System Actors/Users

In the “System Actors/Users” section, we define the users who will have access to the system with a brief description about their roles.

As an example, we can use a table to represent actors and their roles:

User/Actor	Role	Comments
Student	Review schedule

Functionality

Then comes the “Functionality” section in which each of the roles/functions is described clearly. As a best practice, you can give a little description about the functionality, the expected fields to be manipulated and the actions to be performed to achieve the required function.

Example:

After logging in to the system, the student should be able to review the schedule by viewing the list of subjects, dates and time. Fields to be accessed by the student can be:

Actions to be performed by the student are:

GUI Requirements

The “GUI Requirements” section headlines the user needs for the GUI. It can describe the look and feel, include some screen shots or refer to the prototype.

Non-functional Requirements

The “Non-functional Requirements” section includes the user’s requirements regarding hardware and software requirement of an application. It also talks about application performance, number of normal and concurrent users, page response time. They address business risk.

Non-functional requirements are properties the product/project must have, such as the desired look and feel, usability, performance, cultural aspects, availability, reliability, maintainability, extensibility, security and so on.

Questionnaires

It is also healthy to use questionnaires. Questionnaires help getting quick and precise answers to vague requirements. A proposed template is:

Signoff

Signoff is the final and most important step in the requirements gathering process. By signoff, the requirements should be freezed and later request for changes should be treated separately. Before signoff, it is a good practice to take a second opinion about the requirements, it is preferable to involve technical opinion in the requirements to ensure their feasibility before finalizing the agreement with the customer. To ensure the effectiveness of the requirements, it is better to review them with the customer before the signoff process.