Functional Requirements
Introduction
Functional requirements are the things the software provides to the user. They describe the features and functions of the software that are required to meet the user's needs. A list of these requirements should tell you how the system is going to be useful and the value that it provides.
Describing Functional Requirements
The level of detail in functional requirements is dictated by the phase of the project and the target audience. An initial set of requirements might be high-level and focus on the overall functionality of the system. As the project progresses, the requirements will become more detailed and specific.
Perspective
Identifying and communicating functional requirements in not just a matter of the technical team writing down what they think the software should do. This approach tends result in a list of features that the engineers are excited to implement, but that may not be what the user actually needs.
A better approach is to involve the users and stakeholders in the process of defining the requirements. This can help to ensure that the requirements are aligned with the goals of the project and the needs of the user. It can also help to identify requirements that may not have been obvious to the technical team.
It is important to consider the perspective of the user and the business. All functional requirements should be written from the perspective of a stakeholder, so that the value of the feature is clear. This will help ensure that the requirements are aligned with the goals of the project.
The technical viewpoint is still important, but it should be used to inform the requirements, rather than drive them. The engineers can help to determine if some request is feasible, or if there is a better way to achieve the desired outcome. They need to be involved in the process of refining and clarifying the requirements, but the focus should always be on the user and the business.
Acceptance Criteria
Every requirement should include a way to determine if the feature is finished. This is called the acceptance criteria. The acceptance criteria should be specific and measurable, so that there is no ambiguity about whether the requirement has been met.
A lack of clear acceptance criteria is one of the most common reasons for project delays and misunderstandings. If the team is not clear on what is expected, they may spend time working on the wrong thing, or they may deliver something that does not meet the user's needs. If the requirement is ambiguous, the engineers may interpret it in different ways, leading to inconsistencies in the implementation or features that no one wants.
User Stories
The most common way to describe functional requirements is through user stories. A user story is a short, simple description of a feature told from the perspective of the user. It describes what the user wants to do and why they want to do it. Including the perspective lets the team understand who benefits from the feature. This can help to ensure that the feature is aligned with the goals of the project and the needs of the user.
User Story Template
When you are first learning to write user stories, it can be helpful to follow a template. The most basic template is:
As a [type of user], I want [some goal] so that [some reason].
For example:
As a customer, I want to be able to view my order history so that I can track my purchases.
As an admin user, I want to create a complex password so that my account is secure.
The template is a useful starting point, but it is important to remember that the goal is not to fill in the blanks. The goal is to communicate the value of the feature to the user. The template is just a tool to help you get started. As long as you have clearly identified who benefits from the feature, what they actually want to do, and why they want to do it, you have a good user story.
The why is often the most important part of the user story. It helps to ensure that the feature is aligned with the goals of the project and the needs of the user. Without it, there isn't a clear way to prioritize the feature or determine if it is successful.
Another common template is the Gherkin syntax, which is used in behavior-driven development (BDD). It is similar to the basic template, but it includes the acceptance criteria as a direct part of the user story:
Scenario: [some goal]
Given [some initial context]
When [some action is taken]
Then [some outcome should be observed]
And [can continue with more outcomes]
Given that I am an account admin, when I create a new user, then the user should receive an email with their login information.
Notice that this template provides the same three main pieces of information. It identifies the user, it explains what they need, and it shows why they need it.
Once you gain more experience writing user stories, you may find that you don't need to follow a template at all. You will be able to write user stories that are clear and effective without needing to fill in the blanks. The important thing is to focus on the user and the value that the feature provides.
INVEST Criteria
Just following the templates will lead to writing a lot of mediocre user stories. To write good user stories, you need to go a step further and consider the INVEST criteria:
- Independent: The user story should be self-contained and not dependent on other stories.
- Negotiable: The user story should be a starting point for a conversation, not a contract.
- Valuable: The user story should provide value to the user or the business.
- Estimable: The user story should be small enough to estimate accurately.
- Small: The user story should be small enough to be completed in a single iteration.
- Testable: The user story should have clear acceptance criteria.
Trying to meet all of these criteria can be challenging, but it is a good way to ensure that you are writing user stories that are useful and effective.
Common Problems
Some of the most common mistakes that I've seen when writing user stories are:
- Writing from the wrong perspective: It is easy to get caught up in the technical details and forget about the user. Even when following the template I frequently see "As a developer..." instead of considering the actual user.
- Writing about implementation: User stories should describe what the user wants to do, not how the software will do it. This is a common problem when the technical team is writing the stories.
- Writing vague stories: If the story is not clear, it is impossible to know if it is done. This is often a result of not understanding the user's needs or not having a clear goal.
- Writing stories that are too big: If the story is too big, it is hard to estimate and hard to complete in a single iteration. Slicing stories into smaller pieces is critical for agile development.
Example User Stories
Here are some examples of user stories for a course management website. Most of these are intentionally bad examples, to illustrate some of the common problems. After each story, I review the problems and suggest improvements.
User Story 1
As a student I want a button to show all my current assignments so that I can see all the assignments that I have.
The main issue here is what is called parakeet value. The so that section merely repeats what the user is asking for. It doesn't provide any additional value or context. A better version might be:
As a student I want to see all my current assignments so that I can plan my study schedule.
User Story 2
As an instructor I want to see how many students chose each option for a multiple choice test so that I can improve my questions for future tests.
This story is better, but it is still a little vague. It leaves some open questions that will need to be clarified before implementation. As acceptance criteria get created, we would want to include more details about what the instructor should see and how they should interact with the data. What page are they starting from? How will the UI look? What data should be displayed?
User Story 3
Improve performance of the grades page.
This story is pretty bad. It is vague, it doesn't explain why the performance needs to be improved, and it doesn't provide any guidance on how to measure success. It isn't written from the user's perspective, and it doesn't provide any value to the user. A better version might be:
As an instructor I want the grades page to load in less than 2 seconds so that I can quickly access student grades during class.
User Story 4
As a developer, I want to delete out of date profile pictures from the database so that it will save costs.
This story is written from the wrong perspective. It is a technical task, not a user story. What value would doing this provide to the user? What is the cost now? How much would be saved by doing this? A better version might be:
As a user I want my old profile pictures to be removed so that I can keep my images private.
The new version is still a little vague, but it is a step in the right direction. It is written from the user's perspective, and it provides some context for why the feature is needed. You could also write this from the perspective of the business:
As a business leader I want to reduce storage costs by removing old profile pictures so that we can save money.
This version is more focused on the business value, but it is still a valid user story. It is important to remember that the user can be the end user, or it can be the business or another stakeholder.
User Story 5
As the on-call engineer I want you to investigate why this alert is firing in production and file a ticket to fix the issue.
Unfortunately, this is a user story that was actually assigned to someone I know. It is a perfect example of what not to do. It is a technical task, not a user story. It is written from the wrong perspective, and it is not clear what value it provides. Was the alert triggered by a valid event? Is it a false positive? What is the impact of the alert firing? What is even going on here?
User Story 6
As an instructor I need to save my list of quiz questions so that later I can save a copy, print, or email the list for other uses.
The biggest issue with this story is that the so that section is overloaded. It is trying to do too much and should be split into multiple stories.
User Story 7
As a the engineering manager, I would like student logins to time out and log off after a preset number of seconds in case they leave their computers unattended.
This story is written from the wrong perspective. It could easily be rewritten from the perspective of the student. It is also missing an explanation of why the feature is needed. What is the risk of leaving the computer unattended? What is the impact of not having this feature?
As a student I want to be automatically logged out after 5 minutes of inactivity so that my account information is secure.
User Story 8
As a student I want to automate sending a complaint email to any professor and the department chair any time that any of my scores are below some chosen threshold so that I save time and ensure timely graduation.
This story is definitely too large in scope. It is trying to do too much and should be split into multiple stories. It is also a little vague. What is the threshold? What should the email say? What is the process for handling the complaint?
We should probably also investigate how a student got access to our ticketing system.
Conclusion
Accurately describing what the system will do for the user is a fundamental part of software development. The functional requirements are the foundation of the project, and they should be clear, specific, and focused on the user's needs. User stories are a common way to describe functional requirements, and they can be a powerful tool for aligning the team and ensuring that the project is successful.