Many software project team members are unfamiliar with, or intimidated by, the task of documenting requirements. I have to admit that I was one of them years ago. The idea of writing pages of requirements - instead of writing code - was not a pleasant one.
What team members don’t realize is that requirements do not have to be difficult or voluminous. There are simple steps you can take to start documenting requirements, and the benefits are significant. For those who are new to the subject and need to write requirements, I recommend starting with use cases.
What is a Use Case?
A use case can be defined as a user’s end-to-end interaction with a system to achieve a specific goal. A good example of a use case is: "Customer buys a soda." We say end-to-end because we will outline one specific and complete interaction with our system. It will have a beginning and an end, as well as a specific goal.
Use Case Briefs
How do you get started without having to write pages of documentation at the outset? You start by writing use case briefs. A use case brief is a one line statement of the use case. "Customer buys a soda" is a simple and effective example of a use case brief. You can choose to include both a title and description. Below is the list of use case briefs that were created while developing EdgeRM’s Attachments functionality:
- Add an Attachment to an Entry
- Delete an Attachment
- View the list of Attachments for an Entry
- Download an Attachment from the Attachments list
Creating this list enabled me to think through and determine the different ways a user would interact with EdgeRM when working with file attachments. Each brief represents a separate and complete interaction with the application being developed. This first step - coming up with a list of use case briefs - will improve your understanding of the scope of your system. You may come back to your briefs later to add to or revise your list as your requirements evolve.
Once you have a list of briefs you are comfortable with, you will then be ready to add more detail by writing your use cases.
First Use Case
The level of detail you choose to include in your use cases will be based upon the needs of your project. The following format is a satisfactory starting point. You may customize it according to your needs, as you become more comfortable with writing use cases.
Title: Add an Attachment to an Entry
Description: Allow users with appropriate rights to add a file attachment to any specific requirement or other list entry.
Primary Actor: EdgeRM User
Who is interacting with our system? This is usually an end user. We could also be more specific by specifying a job title or user type (ie: Business Analyst or Administrator)
Success Guarantee: Attachment is added to the attachments list for this entry
The success guarantee outlines conditions that must be met for the user to consider this use case to be completed successfully.
Preconditions: User must have Edit access to the List or the Project
Preconditions define the conditions that must be in place before this use case starts. In this example, only users with Edit access will be permitted to add an attachment. If users do not have Edit access they will not even see the Add Attachment button.
Triggers: User creates a document or file related to the requirement
What event causes the use case to take place? For an order processing system, the trigger for a use case titled Ship a widget could be User has submitted a widget order through the web site.
Main Success Scenario:
1. User browses to a Project List and views a specific Entry
2. User clicks the Attachments tab
3. User clicks Add Attachment button
4. User selects a file, enters an optional description and uploads it.
5. File is uploaded and saved
6. User will now see an updated Attachments list
Here we list the specific steps that take place to complete the use case. You could also call this the "happy path." These are the steps a user takes if everything goes according to plan with our scenario.
Extensions:
3a. User does not have Edit access and does not see the Add Attachment button
Here we list any deviations from the main success scenario. Our goal here is to document how the system will handle user or system errors, such as a user filling in a submission form improperly, or alternative scenarios such as a user not having the required access rights.
Notes:
Add any miscellaneous notes that will aid in understanding, or business rules that apply, such as the formula for a financial calculation.
That completes our first use case. Remember that use cases may have as much or as little detail as you choose based on the needs of your team or project.
After writing your first set of requirements, you should review them as a whole and identify any inconsistencies or areas where more detail or clarification is needed. At this point you are concerned with analyzing and revising your current set of use cases. Be sure to do so before you start documenting the next set of functionality.
Dividing your application into functional areas, such as attachments, user account management, or content search will help you develop your use cases. Breaking up the task of writing requirements will make it more manageable. Throughout this process you want to make sure that you don’t fall into the trap of trying to write too much at one time.
An Iterative Process
Writing requirements should be an iterative process, allowing you to take time to step away from the areas you have been analyzing. This will enable you to revisit your writing with a fresh perspective. It is also an opportunity to perform preliminary design tasks, or solicit feedback from other team members.
If you come across areas of confusion - resulting in lengthy one-on-one or group discussion with other team members - you should clarify your use case. Don’t rely on memory of prior conversations or prior email correspondence to guide the development of your application. You’ll want this new information documented for current and future team members in the event that you must revisit a piece of functionality months later and answer the often asked question: "Why did we build it this way?"
Benefits
The advantages of good requirements practices for software project teams cannot be ignored. Requirements that are well documented and organized will put you on the path towards improved development efficiency and product quality. The development team will gain a more in-depth understanding of what they are creating and the challenges that they may encounter during the process. By documenting the functionality, the entire team is able to work collaboratively and as a result more effectively. Of equal importance is the improved communication with business stakeholders, project stakeholders and end-users.
Summary
- Do not be intimidated by requirements or use cases - break up the task of documenting requirements into manageable areas of functionality
- Start small and simple: write briefs and then a handful of use cases
- Take time away from use cases to perform design tasks or solicit feedback
- Good requirements promote clarity and minimize rework
With any software development project there exists the possibility that requirements will change, as a result of requests from business stakeholders, feedback from customers, development constraints, or other factors. While use cases allow you to manage the requirements, Agile software project management practices such as Scrum enable you to react to change.
I will be posting my thoughts regarding Scrum and its value in the development process at a later date, so be sure to subscribe to the RSS feed for this blog.
Recommended Reading
by Karl E. Wiegers
by Alistair Cockburn
