Documenting Requirements

The language of requirements is a challenge to explain: there is an art involved in writing declarative statements that specify what needs to happen without inadvertently limiting the implementation.   Certainly, the choice of words is important: words like “select” and “supply” are more vague than “click the radio button for” and “type into the text box,” but there’s more to it.  I’ll elaborate on that in a future post.

I continue to be more convinced that multiple methods of delivering requirements are needed to draw a complete picture.  So even though one might have the language challenge under control, various types of models (both graphical and verbose) can help to provide views into the system’s requirements from all sides.  But how do they relate to each other, and how do the models relate to the declarative statements that provide the granular detail of what is needed?

The methodology I’ve seen implemented most frequently, when boiled down to brass tacks, is just interviewing and observing users and identifying requirements, and then backing them up with more intricate system models.  The more I reflect, however, I think there may be a smarter way.  One approach I’ve seen from a few sources is to depict the system’s primary uses in the form of use cases, which can be further broken down into any number of scenarios that depict the use case with specific input values and paths through the use case; and then, writing requirements that support each use case.  One point made in a highly recommended article at is: requirements that don’t tie back to a use case may be a warning sign of missing use cases.   Working through a deliberate methodology like this might be a  step towards preventing any significant gaps in requirements capture.

The above article from TechTarget also considers data elements, and recommends entity-relationship diagrams to zero in on the data elements.  As a product manager, I see that fitting in a little deeper into the cycle at the business analysis/design stage, not at the customer requirements/analysis stage.  What do you think?


~ by John Peltier on December 28, 2008.

One Response to “Documenting Requirements”

  1. Hi John,
    Excellent thoughts. Use cases are a really good foundation for gathering, organizing and communicating. The really valuable thing about them is its easy for the domain experts to look at them and say, “well, yes, this is basically correct, except here.” Use cases are great for defining behavioral requirements of a system. Other type of requirements, like performance requirements, SLA requirements, etc that are not necessarily behavioral from the perspective of the users of the system are necessary as well to fill in the missing pieces of the picture (traditionally, I think far too many people focus on non-behavioral aspects and dive right into technical design too quickly). As you mentioned, if there isn’t a good connection between use cases and requirements, that’s a yellow flag that something is missing or misunderstood.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: