Agile projects are often prone to issues related to requirements and design clarity, especially when distributed teams are involved. One of the biggest quality levers in my opinion is "design" - both functional and technical. Putting thought upfront on the requirement and the system visualisation of the functionality and all its dependencies is one of the best ways of improving quality. I've found the concept of a "mini-spec" the right balance between zero documentation and over-documentation both of which can kill an agile project, especially for projects that already have a base architecture defined and the work is mostly in implementing user stories. User stories are broken down into chunks that can fit within a sprint and defined with sufficient details that allow upfront thought and debate as well as clarity required for implementation and testing. A mini-spec captures the below points explicitly. A simple mini-spec review with the technical and domain SMEs (incl. QA) will provide the opportunity to capture many potential issues upfront. Mini-specs have the benefit of forcing developers to think through many areas that will help make their effort lead to ultimate success. Completed mini-specs are used to enable both developers and QA engineers with implementation, test design and testing, and facilitates an efficient development workflow at a user-story level.
<<begin mini-spec>>
Feature Overview - A couple of lines explaining the feature.
Operational Requirements, if any
These are requirements that may not be obvious when thinking about the end user functionality but are needed to enable operational folks to ensure smooth running in production. Eg. this may involve configuration options, admin reports, alerts and monitoring requirements etc. Having this placeholder helps developers put themselves in the shoes of the operational folks upfront rather than when it's too late.
<<begin mini-spec>>
Need - Why is the feature required. What problem does it solve. Business objective(s) it is trying to achieve.
Validation/Key success criteria - How do we know the feature will meet the need mentioned when rolled into production? If possible some measurable criteria that can prove the feature meets its intended need once it is implemented and put into production. This derives from lean-startup principles and forces the developer to think through the end objective.
Operational Requirements, if any
These are requirements that may not be obvious when thinking about the end user functionality but are needed to enable operational folks to ensure smooth running in production. Eg. this may involve configuration options, admin reports, alerts and monitoring requirements etc. Having this placeholder helps developers put themselves in the shoes of the operational folks upfront rather than when it's too late.
Approach and Design
- Functional components and work involved. Eg. what happens in the UI (add a new screen, modify an existing screen...), business layer (add these new APIs...), data layer (new data tables)...
- Functional components and work involved. Eg. what happens in the UI (add a new screen, modify an existing screen...), business layer (add these new APIs...), data layer (new data tables)...
- Where this user story treads into new cross cutting concerns that are not part of the existing base architecture, these designs need to be elaborated in full. Even better if skeleton code/architecture POCs are done for these elements. (eg. first time long polling is used, first time asynchronous jobs are required in the application etc. etc. - first time anything architecturally significant is needed to implement the user story - ideally such work should be identified upfront and allocated to a seasoned developer/lead)
UI/UX (if applicable)
- UI/UX. Level of detail will depend on the state of the team. If everyone understands the base UI standards and expectations, keep this simple and descriptive. Otherwise, this can even be wireframes or mockups.
- UI/UX. Level of detail will depend on the state of the team. If everyone understands the base UI standards and expectations, keep this simple and descriptive. Otherwise, this can even be wireframes or mockups.
Dependencies - Components, requirements etc. affected by this feature. Especially upstream and downstream systems. Requirements/features pushed out to future sprints that will depend on this feature.
Assumptions - Assumptions we're making that are critical for success in terms of environmental dependencies, sequence of work order etc.
Positive test cases - What should happen when the expected conditions/input provided
Negative test cases - What should happen when unexpected conditions/input provided
Positive test cases - What should happen when the expected conditions/input provided
Negative test cases - What should happen when unexpected conditions/input provided
<<end mini-spec>>
In the design factory model, user stories are elaborated into mini-specs by an independent team whose only job is to interact with clients and elaborate these features and also be proxy between clients and the development team. This creates a backlog of "implementable" user stories that can be included into implementation sprints. The advantage of this approach is that it eliminates a signifiant amount of wasted time by developers waiting for feedback.
Post implementation reviews of user stories can also be aligned to the mini-specs, where the developer showcases the user story and shows the functionality as well as the unit tests working.
Developers should also be involved in evaluating the success of the implemented feature in production in terms of the validation criteria. This increases their sensitivity towards the business outcomes of their efforts and helps build a lean-startup mentality across the entire team.
