crmcog: Documenting Requirements

Even after being in development projects for more than a few years now, I am always not far from being awe-struck at every requirement phase we have had (well, almost). The process of gathering and validating requirements, and converting everything to specs that a developer can understand, and maintaining traceability through all the rewrites and changes - are the most critical phases that always excite and worry me. Documenting all these in a language that finds common acceptance across user groups (& probably, across cultures) is, well, crucial to say the least (ALM tools not withstanding).

How well do you indeed document requirements? There may be entire books written on the subject, but where should one start? The following summary and lists should help one think in the right direction. A lot of it seems direct and too easy - I would think so too, but there have been instances where I was too busy to take note in a few of the projects.

Structure and Language

Two things that cause the max impact to the requirement document, and simple in hind-sight. The structure is fairly straight forward - you just group user requirements into buckets, and order it in a way that makes sense to the stakeholders.

Evaluate each statement of a requirement against the following list to apply the "few good rules".

Correct: Speaks for itself, doesn't it?
Complete: Should not be open-ended, and should carry forward on its own weight to functional spec

Avoid use of "including ...", "not limited to "
Don't make subjective or vague statements
Avoid use of 'TBD', but do note that this is not disallowed

Clearly state factors that have caused the exercising of that option
Describe the conditions that will remove TBD

Consistent: Consistency in description, language, and functionality expectations
Bounded: Measurable conditions have to be described and relative statements have to be avoided

"System shall provide response time less than or equal to 5 seconds" is better than "System shall provide quick response times"

Unambiguous

You cannot have a requirement listed but at the same time excluding from scope

While the use of language becomes a hot debate in some circles, I try to apply simpler rules:

Use of "shall" (vs. use of "will")
Use of definitive sentences that are deemed complete. Do not use "etc.", "including ... " and such terminologies which leave things to interpretation or imagination
Avoid usage of double negatives in a sentence
Simple to understand and well articulated

Each requirement should be unique in the set of requirements identified for a project or a program, and be identifiable as such. Inputs from all stakeholders - business and technical teams, and consideration of external environmental factors (regulatory policies, organization strategy etc.) are equally necessary. At the same time do not include designs to address a problem or solutions in the requirement document.

Handling Changes

This is a separate section since this is what we dislike the most. While change management by itself can be a clearly marked process, do you articulate on how to carry forward these changes to the requirements documentation? An indication of versioning of requirements document, and scoping of individual projects that align with the overall requirements go a long way in bringing enough clarity here.

Important Sections

While customers are free to exercise right on the template structure, it is imperative for us to make sure it has a place for some important sections.

Business Rules and Business process diagrams: While not separate sections, making them part of the core requirements, or wherever needed, will help everyone to stay on the same page. Especially in case of COTS products, implementing business rules will demand a big share of development effort
Non Functional requirements: Everything that is deemed important other than the core business requirements - like performance of the application, security requirements, usability requirements and supportability requirements have to be articulated. Even if the customer does not have this practice, it is never late to educate them and include such requirements in order to bring in enough clarity to business expectations
Regulatory requirements: This is applicable and really important for certain industries like Life Sciences that are subject to intense auditing. For a newly proposed system, or even for changes to an existing system, capture and document requirements around regulatory considerations
Assumptions: Clearly categorise assumptions while documenting them

The above points should act as a starter, but can no way be deemed comprehensive. Documentation standards available from IEEE standards talk about some of these and much more - for software requirements and specs. Evaluate them if you have access to the artifacts - that will be time well spent on establishing standards ourselves. Two of the documents that I liked while browsing through: