I’ve spent the last two blog posts (here and here) focusing on the importance of requirements in software delivery. Something very important to any software delivery – not just in getting deployed the first time, but over its continued life-cycle. With the move to agile delivery – a lot of what traditionally used to be software requirements was shifted to user stories. The purpose of this was to try to convey requirements from a user perspective rather than a technical one and help bring the development teams closer to the end-user or customer.
This initiative was a great one that brought an important shift in a lot of software development teams to become more customer-focused and eventually led to the next trend of DevOps, which brought development teams closer to the operations side as well. However, in this move to user stories, a lot of the importance of requirements was lost and many of the technical details that needed to live with the software for its entirety were also removed.
However, I’m not advocating for the removal of user stories. We still need that important user perspective when coming up with requirements. Rather I believe that technical requirements should co-exist with user stories and in today’s post I want to showcase the difference between both of these, how they can work together and then also give an example of an actual user story that can better articulate the needed technical detail and live alongside it.
Difference between a user story and a technical requirement
Here's a detailed comparison of what a user story and technical requirement should generally provide:
User Story
Purpose: To capture a feature or functionality from the perspective of an end user. To facilitate understanding of user needs and provide a high-level overview of desired functionality. To foster communication and collaboration among stakeholders.
Format: Typically written in a simple and concise format using the "As a [type of user], I want [an action] so that [a benefit]" structure. Focuses on the value delivered to the user.
Level of Detail: High-level and often lacks detailed technical specifications. Emphasizes the "what" and "why" rather than the "how". Can be broken down into smaller tasks or detailed requirements for implementation.
Example: "As a registered user, I want to reset my password so that I can regain access to my account if I forget it."
Scope: Broad in scope and can encompass multiple detailed requirements. Used in Agile methodologies to prioritize and manage development tasks.
Requirement
Purpose: To provide a detailed and specific description of what needs to be built. To serve as a formal and precise document for guiding development and testing. To ensure all stakeholders have a clear and detailed understanding of the functionality.
Format: Can be written in various formats such as functional requirements, non-functional requirements, technical specifications, etc. Often includes detailed descriptions, acceptance criteria, constraints, and dependencies.
Level of Detail: Highly detailed and specific, outlining the exact behavior, data inputs/outputs, and system interactions. Includes technical details necessary for implementation.
Example: "The system shall provide a password reset feature that allows users to receive a password reset link via their registered email. The link shall be valid for 24 hours. Users must enter a new password that meets the complexity requirements (at least 8 characters, including one uppercase letter, one number, and one special character)."
Scope: Narrower in scope, focusing on specific aspects of the system or functionality. Used in both traditional and Agile methodologies for detailed planning and execution.
If that proved difficult to follow, I’ve further summarised it as:
User Story: High-level, user-focused, and value-driven. Captures what the user needs and why, often used in Agile environments to manage development priorities.
Requirement: Detailed, specific, and technically focused. Provides explicit instructions on what needs to be built and how it should function, ensuring all technical and business needs are met accurately. While a user story can be completed, a requirement will remain persistent and can alter and change outside of a user story.
Combining actual implementation
As mentioned, I believe both user stories and requirements can live side-by-side quite easily, with user stories used for tracking work required for deployment and releases – and requirements documented separately with the intention of mapping back to the code and tests and living along with it.
Essentially you would want the split of User Story and Requirement to work as follows:
User Stories: Used to capture the high-level needs and priorities of the end users and to facilitate Agile project management.
Requirements: Derived from user stories to provide the necessary detail for developers to build the functionality. User stories are often decomposed into multiple requirements.
Whereas a user story is often tracked in an Agile delivery tool like Jira or AzureDevOps, a requirement should be tracked in a separate document repository where it can still be linked back to both the Agile tooling and the code repository. User stories are normally written almost exclusively by analysts in the team with consultation from the rest of the team, whereas requirements tend to be more technical in nature and may often be done by the entire team.
A Sample User Story
However, I thought it would not be a complete article If I didn’t give an example of the type of information that should be considered in a user story that best supports the technical requirements. So below, I’ve taken the common example of a basic login system and detailed how it can be crafted into a set of smaller tasks that can provide the development team with the information they need to easily code and test the solution that best meets the needs of the enterprise.
I’m not trying to capture the perfect user story and the reality is this epic and user story can be broken up into several smaller components. The focus is rather on the information that needs to be captured to make the user story work best for high-delivery from a technical perspective It’s a lot of information, but a lot of this information gets easier to update the more familiar people are with the system and doesn’t need to be repeated where previously requirements/user stories already cover these things.
I’m mixing some of the requirements into this user story so that it is stated, but ideally, some of these may sit in that longer-term requirement and perhaps be linked back to that document repository. I’m just documenting everything in one place to make it more readable.
Epic for Login System with API Backend
Overview
As a user, I want to securely log in to the application so that I can access my personalized content and services.
User Story
Title: Secure Login System with API Backend
Narrative:
As a registered user, I want to log in to the application using my username and password, so that I can access my personalized content securely and efficiently.
Requirements
Functional Requirements
User Authentication Priority: High Description: The system must authenticate users using their username and password. Acceptance Criteria: Users must enter their username and password. The system must validate the credentials against the database. If valid, the system must generate a session token. If invalid, the system must display an appropriate error message that states the following: “xxxxxx”.
API Endpoint for Login Priority: High Description: Provide an API endpoint for user login. Acceptance Criteria: The API endpoint must accept a POST request with username and password and return with a 200 success message when accurate. <detail actual API payload and response here> The API must return a session token upon successful authentication. The API must return an error message for invalid credentials. <insert error message exact wording here> The actual API payload needs to contain the following <detail actual ASPI payload here> Invalid responses of 500 and 300 should also be detailed with the relevant error message and sample payloads of what might cause them too.
Session Management Priority: High Description: Manage user sessions securely. Acceptance Criteria: The system must generate a unique session token upon successful login. The session token must have an expiration time of x minutes. The system must invalidate the session token upon logout.
Password Reset Priority: Medium Description: Allow users to reset their password if they forget it. Acceptance Criteria: Users must be able to request a password reset link via email. The system must generate a secure, time-limited reset link. Users must be able to set a new password using the reset link.
Account Lockout Priority: Medium Description: Implement account lockout after 3 failed login attempts. Acceptance Criteria: The system must track failed login attempts in the API/DB layer. The system must lock the account after a predefined number of failed attempts. The system must notify the user of the account lockout and provide a way to unlock the account <actual process should be detailed too with exact working>.
Security Requirements
Data Encryption Priority: High Description: Encrypt sensitive data in transit and at rest. Acceptance Criteria: All API communications must use HTTPS. User passwords must be hashed and salted before storage. Session tokens must be securely generated and stored.
Multi-Factor Authentication (MFA) Priority: Medium Description: Provide an option for multi-factor authentication. Acceptance Criteria: Users must be able to enable MFA for their accounts. The system must support common MFA methods (e.g., SMS, authenticator app). Users must enter the MFA code in addition to their password during login.
Audit Logging Priority: Medium Description: Implement audit logging for security events. Acceptance Criteria: The system must log all login attempts (successful and failed). The system must log password reset requests. The logs must include timestamps and user identifiers.
Performance Requirements
Scalability Priority: High Description: The system must handle high volumes of login requests. <actual details should be provided> Acceptance Criteria: The system must support scaling out by adding more servers. The system must maintain performance under peak loads. <actual details should be provided>
Response Time Priority: High Description: Ensure the login process is fast and responsive. Acceptance Criteria: The system must process login requests within 500ms under normal conditions. The system must degrade gracefully under heavy load when exceeding x number of users, ensuring that login remains functional even if slower.
Data Requirements
Data Integrity Priority: High Description: Ensure data integrity for user information. Acceptance Criteria: The system must validate user input to prevent invalid data. The system must handle data conflicts and maintain consistency.
Data Retention and Privacy Priority: Medium Description: Comply with data retention policies and privacy regulations. Acceptance Criteria: The system must delete inactive accounts after a specified period. The system must allow users to request data deletion. The system must comply with relevant data protection regulations. These should be detailed based on what is required by POPI/GDRP, etc.
Non-Functional Requirements
Usability Priority: Medium Description: The login interface must be user-friendly. Acceptance Criteria: The login page must be intuitive and easy to use. The error messages must state XXX.
Maintainability Priority: Medium Description: The system must be maintainable and easy to update. Acceptance Criteria: The codebase must follow best practices for readability and modularity. Passing the relevant scans, etc. The system must include documentation for developers.
Compliance Priority: High Description: Ensure the system complies with relevant regulations and standards. Acceptance Criteria: The system must adhere to security standards such as OWASP. The system must comply with data protection regulations.
Acceptance Criteria for Overall System
The login system must meet all specified functional, security, performance, and data requirements.
The system must pass security audits and penetration testing.
The system must perform reliably under expected and peak loads. <actual details provided here>
Unit testing needs to be conducted and meet a 90% code coverage criteria
All functional testing needs to be automated
Pipelines have to be green once all changes have been made.
Monitoring is in place for the new feature in <add monitoring tool here> with all the criteria required by the service engineering team
The system has been deployed into a test environment successfully and rollbacked successfully as well.
Summary
This user story outlines the requirements for a secure, performant, and compliant login system with an API backend. By prioritizing these requirements, the development team can ensure a robust and user-friendly authentication experience.
We need to align user stories and technical requirements together to get the most out of software delivery and provide the team with the best platform for achieving software that is both of a high technical standard, can be delivered in an independent and agile manner, and aligns well with the needs of the business and end user.
Comments