Requirements – To Detail or Not Too Detailed

In recent years, I have discovered that more and more organizations are writing use cases to clearly understand the behaviors of their systems.  Working with these organizations, I usually get the question “What Use Case standard should we utilize?”  The answer depends on the project situation.  I have utilized two simple use case formats that will help you document use cases in some of the following common situations:

 

1. Drawing out requirements for new features or functions
2. Writing requirements on short iterations (e.g. Agile)
3. Redesigning a process or feature or function
4. Writing detailed requirements on incremental or longer projects

For Drawing out Requirements or Writing Requirements on Short Iterations

Use cases are a great way to discover requirements.  Stakeholders find the narrative format easier to understand than a long list of requirements because they can see the behavior of the system.  This is very helpful in situations where you have a brand new feature/function.  The use case initiates a visualization of the new feature, which can then be iteratively modified to fit the needs of each stakeholder.  This allows for eliciting ideas on how the new feature may or may not let an actor reach its goals in the current system.  For this type of use case, create a high-level view of how you think the new feature will behave.  Create the main basic flow and walk through this flow of the new feature with stakeholders.  Once the basic flow is accepted, then consider the alternative flows at a high level.  These alternate flows are going to help you find missing requirements that you may not have thought of for the new feature/function.  This is going to guide you to superior requirements that are well thought-out and more complete.

The goal for this type of use case is to provide quick analysis and acceptance, usually in a live review session.  It is assumed that you are working in a group with good internal communications when using this format for a project with short iterations. 

Here is a simple format for such a use case:

Use Case Name:

Scope: the extent of the new feature that will be designed/developed.

Primary Actor:

Triggers: This describes the event(s) that causes the new feature to be initiated

Preconditions: This describes all the conditions that are true before the new feature can be initiated.

Postconditions: This describes the change(s) the new feature will have in the current system, positively and negatively.

Basic flow: A paragraph of a high level, top down description of the typical set of actions in which the goal(s) is delivered.

Alternate flows: A paragraph for all the other flows.  Each alternate flow paragraph should start with a condition/trigger and a goal for the alternative flow.  It should contain a high level, top down description of what happens for that condition/trigger, and end with the success or failure of the extension goal.

For Redesigning the Process/Feature/Function or Writing Detailed Requirements on Incremental or Longer Projects

This type of use case is for situations where you need to redesign a process or a function/feature.  If you have existing requirements or use cases, then you have a place to start.  If you don’t (many times, this is the case), then you will need to do one of two things.  If time permits, then reverse engineer the behavior of the process/feature/function in a use case.  This will give you a baseline and a way to validate with stakeholders what is current before you make any changes to the system.  If you don’t have time, then just start documenting the changes.  At least, you will end up with some level of documentation regarding the system behavior, which is better than nothing.

Here is a sample format for a detailed use case:

Use Case Name:

Scope: the extent of the change that will be designed/developed.

Primary Actor:

Triggers: This describes the event(s) that causes the changed process/feature to be initiated.

Preconditions: This describes all the conditions that are true before the changed process/feature can be initiated.

Postconditions: This describes how the changed process/feature will modify the current system, positively and negatively.

Basic flow: This is the top down description of the typical set of actions in which the goal(s) is delivered.  Number the steps to make the sequencing stand out.  If you are starting from an existing use case, then I would bold the steps that reflect the changes.  This will allow the reviewer to hone in on areas that are being redesigned.

Alternate flows: These are all the other flows whose steps are also numbered for sequencing.  It starts with a condition/trigger and a goal for the alternative flow.  It contains a sequence of action steps describing what happens for that condition/trigger.  It ends with the success or failure of the extension goal.  Failure handling description is important to this type of use case because you will discover new business rules.  Again, if you are working from an existing use case, then I would bold the steps that reflect the changes to the process/feature.

You should have a template for a simple and detailed use case definition and utilize one when the situation arises.  Don’t over analyze too much about the exact format for your organization.  But do create detailed-enough formats where it’s easy for you to review with your stakeholders.

Don’t forget to leave your comments below

---

Zeena Kabir is a Sales Engineering Consultant for Blueprint Software, the leader in requirements definition and visualization software. Prior to Blueprint, Zeena has worked 20+ years in the IT field in the areas of requirements engineering, testing, and development. She holds a Bachelor of Science degree in Computer Science and a Master of Science degree in Software Engineering from the University of Maryland. She resides and works with many IT organizations in the Mid-Atlantic region.