Documenting Requirements - A Few Thoughts

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:

• 830-1998: IEEE Recommended Practice for Software Requirements Specifications. http://ieeexplore.ieee.org/servlet/opac?punumber=5841
• 1233-1998: IEEE Guide for Developing System Requirements Specifications. http://ieeexplore.ieee.org/servlet/opac?punumber=5982

Back for good

I am back after a long time, had to attend to some serious issues that would have taken away my source of income. And this is not what you want to do in these times of recession.

I have seen a couple of more projects hence and still wonder what makes project teams tick? There are a few people around who actually like what they do for living. Day by day, project by project you see the same mistakes repeated often. The same review comments given out by Oracle and the flurry of fixes. Unless you have a tight grip on ALL configuration objects or have someone interested do it, you are pretty sure to go through the 25 pager that Oracle ES doles out for minor defects in 25 objects!

Anyway, here are a few must-do's in all Siebel projects:

1. Keep Configuration and Scripting best practices handy. Get the team to go through it at least twice and once more to make sure everyone knows the game
2. Quality is everyone's responsibility. Maintain strict traceability on customization and hold team members responsible for deviations. No, I do not mean to thrash them but make them correct mistakes. Pouring over the same code again is punishment enough
3. Appoint a elite review team consisting of 20% of team members. All "critical" development decisions (do we need a separate view or shall I use applet personalization in the same view?) have to pass through these guys. Also, make them directly responsible for all objects/code reviewed
4. Organize fun events every month or so during the development period and announce prizes for people who identify deviations from established standards
5. If your organization has internally developed a configuration review tool, use it frequently during development. If you have no such tool, it is good time to consider developing one

Ofcourse this is not a comprehensive framework, but something I have implemented in a few projects and regret not implementing them in a lot of projects. Do they indeed make sense? What other ways do you follow to sustain quality deliverables? Please comment!