A plethora of possibilities
Many different requirements systems and strategies exist as well as many variations of those systems and strategies. The system that I will recommend is largely influenced by the existing Agile/Scrum ecosystem. Let’s continue this discussion by looking at the different elements involved in the requirements process that I am recommending.
First we need to start with an Abstract. An Abstract represents the initial purpose of a project. Think of the Abstract as both an elevator pitch and a mission statement. It should quickly describe the project to an outsider, but also represent the core motivations and driving forces behind the project. At the heart of most companies, really all companies, is the need to make money. If the company can’t make money the company dies. So, it is also very useful if the Abstract can tie back into how this project will help the company profit.
At the Chicago Institute of Marine Biology, in support of the institute’s mission, we want to do all that we can to protect and bolster the region’s seal population. In support of that goal we need a way for the community to donate to the effort. The donation platform must support multiple payment methods and currencies.
After we have a good abstract, we can begin work on the largest division of requirements for the project. An Epic is a project sized chunk of work to be done. I give my epics a simple name and a type designation. The name just needs to be short and obvious, no code names. Just take the abstract and reduce it to a couple words. The epic’s title does not need to communicate purpose or profit, just goal.
The project type specified in the epic title can be specific to the structure of your organization or it can be generic. For the purposes of laying out a straight forward and simple approach to requirements I will say to use “Internal Application” and “External Application”. These terms are unambiguous and shouldn’t cause any confusion. If for some reason those terms do cause some confusion, I would suggest to use synonyms and label your epics with something like “In-House App” and “Client Facing App”. What is important is the clear distinction between something used by customers and something used by employees. Customer applications require more polish while employee applications just need to exhibit the correct functionality.
Donation Platform – Customer Application
An epic is comprised of many Features. A Feature is a deployable section or slice of functionality. It is not the entire application, but a feature should be capable of deployment and use in the application. In the spirit of Agile, we want to release as early as possible so that we may begin to receive feedback and make the appropriate adjustments. A feature is similar to an epic in it’s format. The first part is a simple, just a couple words, description of the goal of the feature. The second part is a label describing the feature’s type. The available types for a feature are System, Functional, and User Experience.
System requirements are devoid of notions that depend on or reference the user interface. System requirements are also absent of any kind of performance characteristics; such as response times, quality of service, or any other system level agreements. Lastly, system requirements are the least likely to change because they represent the core functionality of the system.
Functional requirements fill one of the gaps left by the system requirements. Functional requirements can be used to specify response times, quality of service, or any other service level agreements. Any need to describe the performance of the system will be a functional requirement. Functional requirements may reference the user interface, but only as it pertains to performance. For instance, we can say that every page in the web application must load and be usable by the customer within 3 seconds; however, we would not mention buttons being clicked by the user.
User Experience(UX) requirements are used to describe exactly that, the User Experience. UX requirements are a combination of the User Interface(UI) design and performance as it relates to the UI. As an example. Saying that a page must be fully loaded within 3 seconds would be a functional requirement. However, saying that a page taking longer than 1 second to load should display a loading screen would be a UX requirement.
Accept Donation – System Requirement
Donation Payment Process Time – Functional Requirement
Donation Amounts – User Experience Requirement
The user story is an expression of need for the feature. User stories consist of three parts the role, desire, and justification. The user story is important because it is opportunity to warrant the feature. Properly explaining the need for the feature will help greatly when it comes time prioritize work to be completed.
The user story’s Role is typical in the form “As a [role]” where [role] is replaced with the system/functional/user role that is important to the feature. There is no reason why a Feature can not have multiple User Stories describing different roles having the same desire, likely for different reasons.
The desire expresses a want that the role has and is typically in the format “I want [desire]” where [desire] is replaced with the appropriate want. The expression of desire needs to be appropriate for the type of feature for which the story is being written.
Lastly, the justification is the argument for why this story is important. Without a valid justification it is likely for this story and in turn the related feature be prioritized low or dropped altogether. The justification is usually in the form “So that [reason]” where [reason] is replaced with the justification for the desire in relation to the roles needs. In my experience this is the most difficult part of a user story. It is very easy to determine a want or desire. It is also not too difficult to come up with a role that wants the feature. It seems to be very difficult to determine a proper justification for the requirement to be in the system. What tends to make this part difficult is the brevity of the justification. We can not use a paragraph to describe our need, we only have a portion of a sentence. Unfortunately, there is little I can do to help in this matter. The reasoning for a feature is system dependent and difficult even with experience. What I can say is that it is our professional responsibility to carefully consider the justification for every feature in the system and only allow the features that support the goals of the company and the project to be included in the application being developed. Any feature that is not in support of those goals is a money and time sink, and is detrimental to the company. To be clear, any requirement that does not support the stated goals of the company and the application is harmful to the company.
As a Visitor to the Chicago Institute of Marine Biology
I want to donate money
So that I can contribute to the Save the Seals campaign
The above user story demonstrates the format of a user story, but does not necessarily demonstrate the level of effort needed to properly create quality user stories. Under normal circumstances, I would expect for at least 30 minutes to be spent per user story thinking about why that user story is important and the best wording that could be used to express the story’s importance.
In the requirements style that I am telling you to use, a scenario is an acceptance criteria. Acceptance Criteria are the conditions under which, if met, the feature will be accepted by the Product Owner. Scenarios are named for the action being taken and/or the expected result. Scenarios consist of a context, an action, and an expected result.
The context for a scenarios is in the form of a Gherkin style Given statement. The Given statement follows the form “Given [some condition]” where [some condition] is replaced by the user role or some specific application state that is a precondition of validating this scenario in the feature. It is completely possible and often expected to have multiple Given statements for a single scenario.
The action, again using Gherkin syntax, is in the form of a When statement. The When statement is in the form “When [some action]” where [some action] is replaced with the action to be taken as part of the scenario. Unlike the Given statement. There can only be one When statement as part of the scenario.
Lastly, we have the Then statement. The Then statement is used to state the expected result from configuring and executing the scenario. A Then statement is in the form “Then [expected result]” where [expected result] is replaced with the expected outcome of executing the action given the context. Similar to the Given statement, the Then statement can have multiple instances for a single scenario.
Scenario: Donate Money Greater Than Zero
Given I am a Visitor
And Given I have money
When I donate a positive amount
Then I get a coupon to visit the museum at a discounted rate.
As with the user story, scenarios require a great deal of thought in order to make quality scenarios that will be well understood and meet the needs of development, quality assurance, and the business.
Scenarios must do one more thing that what I have already discussed. Scenarios must state error conditions. Below is an example of a scenario that deals with an invalid donation amount.
Scenario: Invalid Donation Amount
Given I am a Visitor
When I donate a negative amount
Then an INVALID_DONATION_AMOUNT error occurs
The above requirement is a system level requirement. Somewhere in the UX requirements we would define what to do when an INVALID_DONATION_AMOUNT error is received from the system. A single feature may have multiple scenarios, but if you find you are generating more than 3, and certainly if you have more than 5 scenarios for a single feature, it may be an indication that your feature is too large and needs to be broken down further.
That is It for Requirements
A normal system is comprised of hundreds or even thousands of requirements. My argument is that all the requirements should be with the utmost care and consideration. In the next post in this series I will be discussing the arrangement in which activities should take place in any given sprint cycle. As always, I hope this article has been helpful and look forward to any comments you may have.