Ask the Expert

How to search through requirements documentation effectively

We have problems with requirements documentation. There's too much of it, though it seems like we need that much to do an accurate specification. Then again, there is duplication and inconsistent language. Also, some in my team are good at writing their specs and others don't or have to be pushed to do it well. Could you offer some techniques and maybe some tools that would help?

    Requires Free Membership to View

To determine if a particular set of requirements is on target, 'just enough' to get the job done, you must first recognize what is needed. At a minimum the requirements should articulate the answers to the following questions:

Question

Keywords

  • What does the business needs to achieve?

business goals

  • What does the user have to be able to do to accomplish the business goals?

user tasks

  • What does the system have to be able to do to support the user?

system functions

  • What qualities must the system have?
  • Where do these qualities apply?

quality attributes

  • With what rules must the system comply?
  • Where do these rules apply?

policies…regulations

To be successful you will need to pick a set of techniques that provide answers for these questions, but first let's explore some common occurrences which might produce the situation you are experiencing. It is important to understand your current situation and have a good grasp on what would be better and identify some steps forward. Do any of the following situations resonate with you?

Situation

Ramification

Possible Action

Each project must have a requirements document, but little or no guidance offered as to what is expected

  • Requirement documents are provided, but each has a different approach for documenting requirements.
  • When project teams have to work together, the different approaches to documenting requirements really hinder communication and integration.
  • Identify a common set of techniques for defining requirements (vision statement, use case, data model,…).
  • Provide training on each technique and simply state expectations for requirement completeness, compliance and consistency.
  • Walkthrough each work product to ensure expectations have been met.

A 'document-centric' mindset dominates

  • When a 'document-centric' mindset dominates, then 'more is better'. Requirement quality is weighed by the pound (or pages).
  • When the 'requirement-centric' mindset prevails, requirements are viewed as succinct statements (usually a sentence in length) that clearly state what must be implemented. These succinct statements are locally related. The whole nature of the requirement deliverable changes—from a document that includes a lot of extra information to a set of interrelated statements that must be implemented.
  • A 'document-centric' mindset leads to inconsistencies and redundancies usually in a valiant effort to be thorough.
  • Understand the different types of requirements and the very predictable relationship to one another
  • Identify a common set of techniques for defining the different types of requirements (vision statement, use case, data model,…)
  • Provide training on requirement types supporting techniques to facilitate requirements being:
  • complete
  • compliant
  • consistent

Roles are not clearly defined

  • Often the relationship between 'role' and 'job title' is blurred.--project managers write requirements…business analysts scribe meetings, test applications,… This situation can result in requirements of varying quality and as many different approaches as you have people writing them.
  • It is not generally understood that the skill set for eliciting and writing excellent requirements is relatively rare. Many make the assumption that whoever is free can write the requirements. You'll get 'something' but will that 'something' truly define what the system needs to do? Doubt it!
  • Create role definitions (not job descriptions) that clearly state tasks and expectations for each system development role
  • Identify individuals whose natural skills align with each role
  • Provide training to enhance the skill set for each role

Identifying a Set of Techniques
Now, let's tackle identifying a minimum set of techniques. There are, of course, many techniques from which to choose, but the main thing is that the techniques selected should be complementary so that they provide you with a complete picture of what needs to be built.

Question

Keywords

Potential Technique

Technique Purpose

  • What does the business needs to achieve?

business goals

Vision Statement

Project/Product Success Criteria

  • States goals

 

  • States what is meant by 'success'
  • What does the user have to be able to do to accomplish the business goals?

user tasks

Use Case Diagram

Use Case

 

Business Process Model

 

Logical Data Model

 

  • Identifies user tasks needed

 

  • Identifies the steps of each user task
  • Shows relationship between user tasks

 

  • Defines data important to the business and identifies the logical relationships that exist

(Note that these relationships are often some of the rules.)

  • What does the system have to be able to do to support the user?

system functions

  • What qualities must the system have?
  • Where do these qualities apply?

quality attributes

Listing/catalog of qualities needed with references to where each applies

  • States the qualities needed
  • Relates each quality to where it applies without repetition
  • With what rules must the system comply?
  • Where do these rules apply?

policies…regulations

Listing/catalog of rules needed with references to where each applies

  • States the rules needed
  • Relates each rule to where it applies without repetition

Since an approach that is 'just enough' is what is called for, ask yourself if there is anything in this column that is not needed.

No matter how carefully you select the techniques to use there will be circumstances that call for something else. Now, some will use this reality to argue against a standard approach or try to justify 'flying by the seat of their pants' because 'they are different'. If you pick a set of techniques wisely, most projects can effectively leverage them. However, if a project is heavily weighted toward, say, data or rules, a modified approach may be in order.

Modifying Your Approach
I was on a project once that was very data-centric and there were relatively few user tasks or rules to follow. The company had a Requirements Development Process with named technique, but unfortunately they had not addressed an approach for a data-centric development project. In our case, the logical data model was a key analysis artifact. We identified our user tasks, but they were not in use cases. The state of the information drove user action—you know, whether it was 'identified', 'reviewed', 'approved',… at one of several different levels in the organization. We developed a Stage-Step Diagram which conveyed the changes in state and the various users who had to take action during that state.

This was working well for our team, but it was not a surprise when we were asked to talk to someone from the Requirements Management Group (RMG). Well, our whole team gathered—the Business Sponsor, Project Manager/Requirements Analyst (that's me), Architect, Developer— and we explained that we had attempted to follow the standard requirement development process using the prescribed techniques, only to discover rather quickly that this approach was not going to produce a succinct and clear understanding of what was needed for this very data-centric project.

We then walked through how we were documenting the requirements. The representative from RMG listened and asked only two questions. The first was addressed to the Business Sponsor: "Do these requirements represent what you need?" The answer: "Absolutely, I wrote a number of them." The second question was directed to the Developer: "Do you know what to build?" The answer: "Sure, we are cranking it out. Then we show Joe, and usually we only have a few easy tweaks to make." Well, if the RMG 'cops' had been the ones to conduct this meeting, we might have been 'busted', but the two questions we were asked got to the heart of whether this this modified approach was working.

Summary
Coming back to the basics, there are certain things the Developer needs to know to be able to build the right system.

The Developer needs to know…

For…

business goals

Context

user tasks

system functions

Building system functionality

quality attributes

policies…regulations

If this information is not available or is not succinct, it is likely that the initial development will not be on target and that the requirements will be discovered during testing. It is important to look at the potential turmoil at the end of the project before deciding what is 'just enough' with regards to eliciting and documenting requirements.

While there are a number of legitimate approaches to requirements, there are some basic actions you can take to ensure that the system development needs of the business are consistently and clearly communicated to your developers:

Requirement Types/Techniques

  • Understand the different types of requirements and their very predictable relationship to one another
  • Identify a common set of techniques
  • Provide training that addresses requirement types and the techniques you have selected to articulate them
  • Simply state expectations for requirement completeness, compliance and consistency
  • Walkthrough each work product to ensure expectations have been met

System Development Roles

  • Create role definitions (not job descriptions) that clearly state tasks and expectations for each system development role
  • Identify individuals whose natural skills align with each role
  • Provide training to enhance the skill set for each role

This was first published in September 2009

There are Comments. Add yours.

 
TIP: Want to include a code block in your comment? Use <pre> or <code> tags around the desired text. Ex: <code>insert code</code>

REGISTER or login:

Forgot Password?
By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy
Sort by: OldestNewest

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to: