In previous articles we’ve discussed requirements from several viewpoints.  We’ve examined the characteristics and attributes of good requirements and differentiated them from business rules.  We’ve discussed the merits of developing requirements in a cascading fashion from business goals through related objectives to enable prioritization.  We’ve also looked at techniques and templates to aid in remembering categories of requirements to explore.  Requirements are so important a topic I could probably discuss them for weeks, and who knows maybe I just will.  Requirement documents can take on many fashions and styles and this week’s focus will be common formats for their expression and capture.

Use Cases – are used to describe scenarios of operation of a system.  Typically unique roles or “actors” are defined, and the use case or actions carried out by those actors as they interact in the variant ways with the system.  As each unique variant is described a process diagram in words is built.  According to Wikipedia, there can be 3 conventional levels of detail for use cases: brief, casual, or fully dressed.  In the fully dressed version use cases contain:

  • a name, number and a version section for identification,
  • goal and summary sections to help clarify the purpose of the use case,
  • actor and stakeholder sections to identify the performing role and affected agent role,
  • preconditions and trigger sections to describe conditions that must exist and event that initiates respectively,
  • basic course of events section that describes the primary and normal scenario,
  • alternative path section that describes exception scenarios,
  • post condition section that describes the change of status after the use case completes, and a
  • business rule section that documents policies related to the use case,
  • general notes section,
  • author and date section

User stories – are used with Agile methodologies.  They are written by the product owner or customer, and they are usually limited to a few sentences that can easily fit onto a 3 by 5 index card.  They are intentionally meant to be brief to keep them from becoming too structured or formal and to promote, well agility.  The idea during design is to encourage conversation between developer and customer, more than extensive documentation.  The specifications will be assured through an accompanying acceptance test.  User stories usually have the form of:

As a [Role] I would like to [do action] because [reason]. 

As the details get filled in through dialog, the acceptance test gets defined and verification occurs in the agile methodology at the end of the iteration in the customer demonstration, using the acceptance test.

Other generic formats – whether downloading templates for free from collaborative shareware sites or purchasing moderately priced forms or templates, or developing your own home grown version, there are many structures and styles governed by no particular standard.  Most will have some or all of the following sections (shown here in the context of a software system development project ):

  • Project /Problem Description section discussing basic needs and business drivers
  • Goals / objectives section
  • Project Approach / Scope
  • Assumptions and Constraints
  • Risks and Dependencies
  • Deliverables and high level milestones or target delivery dates
  • High level budget
  • Stakeholders / Roles
  • Processes – current state and to-be state
  • High level Requirements
  • System interfaces
  • Product requirements
  • Organizational requirements
  • External requirements
  • Usability requirements
  • Performance requirements
  • Operational maintenance requirements
  • Reporting requirements
  • Training / Documentation requirements
  • Infrastructure requirements

What most of these approaches have in common is that they allow multiple layers of granularity from high level to lower levels of detail and specificity.  This supports a progressive evolution into “clusters” of business specification information.

Putting it all together, the example below illustrates how we can maintain traceability between goals, objectives, and requirements, and detailed specifications of our requirements.  Mining a requirement template with categories, you can remember which categories to think about when developing requirements and specifications for any project. 

In the following example involving installation of a home security mailbox, two high level goals and a more specific, measurable, related objective are listed.  Then using a generic document format modeled after a requirement template we capture specifications for the mailbox itself.  In this environment we might have a homebuilders’ requirement template that has general requirement sections around such things as foundation, framing, electrical wiring, plumbing, interiors, landscaping, security, convenience features, homeowners specifications, city/government regulatory requirements, etc. 

Example:

Goal #1 :  I wish to be free from the perils of information theft

Goal #2:  I want to stay out of trouble with the homeowner’s association

Objective #1 (related to Goals 1 and 2): I wish to safeguard the mail delivered by the US Postal service to my house in a way that prevents theft, for a cost no more than $500.00, by the end of the year that complies with the homeowners’ code.

Requirement Specifications using generic template format:

Requirement #1 (related to Objective #1):  Install a security Mailbox

1.1    Homeowners’ specifications

1.1.1          Base must be made of brown brick

1.1.2          Height must be between 3 and 4 feet

1.1.3          Width must be 2 feet

1.1.4          Depth must be 2 feet

1.1.5          Top must be angled 125 degrees

1.2   Security specifications

1.2.1          Mail in lever closes locking mail from manual retrieval

1.2.2          Retrieval from bottom with key

1.3   Convenience specifications

1.3.1          Two retrieval keys

1.4   Governmental Regulations (US Postal service)

1.4.1          Address plate on front

1.4.2          Must be installed no more than 18 inches from curb

Next, we will define the normal retrieval process using a use case format.

Use Case: SecureMailRetrieval 1.0 v1

  • Goal: Retrieve postal letters from a secure mail box
  • Summary:  The owner uses his key to retrieve letters securely from mailbox.
  • Actor:    Homeowner
  • Stakeholders:  Postman, Thieves
  • Preconditions:  Mailperson has delivered mail.  Homeowner has key
  • Trigger:  Mailperson has delivered mail.
  • Normal Scenario:  Homeowner uses key to unlock bottom compartment.  Retrieve mail.  Lock back
  • Alternative Path: Mailbox is empty.  Lock back.
  • Post condition:  Mailbox is empty, mailbox is locked.

               

Finally we will define the Mail delivery process as an Agile user story and acceptance test

User Story: SecureMailDelivery

  • As a Mail carrier, I would like to be able to deliver mail to mailboxes with security compartments without needing a key because I will not have access to homeowner mailbox keys.
    • Acceptance test: Mail carrier has access to input compartment without key.  Once mail is inserted and door is closed, letters cannot be retrieved without key.

 Regardless of what form you use, requirements should be developed with progressively more detail and linked back to the high level requirements, objectives and goals that they originate from.  This helps us organize and make sense out of the forest and trees and leaves of a project’s requirements and related specifications and business processes.