Toggle Menu

Insights / Agile Transformation / What Is The Best Structure For Agile Software Requirements?

December 20, 2012

What Is The Best Structure For Agile Software Requirements?

3 mins read

Often when starting up a new Agile software development project, people ask me the best way to document requirements.  Many teams and Agile purists argue that a formal document is not necessary, that verbal communication and prototyping is sufficient, or that a card on a taskboard is enough transparency.

Unfortunately, some level of documentation is still required to keep stakeholders outside of the team informed of software functionality, or to hand off to a maintenance team after delivery.  This may be especially true for teams transitioning from a waterfall approach, who may be having trouble letting go of their traditional requirements documents.

To try to answer this question, let’s break down a few key concepts for Agile requirements.

What are Requirements in Agile Software Development?

The closest parallel to a traditional functional requirement in Agile development is the user story.  A backlog of user stories is definitely a form of functional requirements documentation.  But often that is not enough detail to constitute a full specification.  And it may not be enough for managers and business owners who are new to Agile.

There are many other artifacts in the Agile/Scrum spectrum that contain ‘requirements’ for successful development, such as Acceptance Criteria, Non-Functional Standards, Conditions of Satisfaction, and Definition of Done”.  When evaluating which is appropriate, it’s good to ask yourself this:  “How do we know exactly what needs to be documented and to what level of detail?”

Documents as a User Story

Because so many different documents can be considered ‘requirements’, it’s important to identify the audience and purpose for what you are documenting.  Ask the same questions one would ask when creating a user story:  “As a ____ I want _____  so I can _____.”  The identification of the consumer and its value can dramatically change the documentation approach.  Why are we creating this document anyway?  Also, consider the time factor of the document:  Is it to communicate what will be built, or what has been built?  Having this knowledge allows you to create a deliverable that meets the needs of the organization while eliminating any waste from the team.

Once you decide the why and the what of your documentation, be careful that it doesn’t try to achieve too much.  I often see requirements documentation at the beginning of the project that ends up as a user guide or maintenance document at the end of the project.  While many elements of the content may be the same, the audience and timing are completely different.

Knowing the expectations of your audience also allows for ‘just enough’ documentation.  Document only what is required for meeting that specified purpose.  Not unlike code refactoring, understand that some rework may be required at the end of a project to update documents or tailor them for their new audience and purpose.

Document in Vertical Slices

One of the great things about Agile development is the cross-functional team.  Everyone works together to create a piece of functionality for the user, instead of creating ‘hand-offs’ between each phase of development.  Consider the same concept for documentation.

Instead of having separate functional requirements, system design documentation, UI mockups, and testing scripts, organize the documentation by feature.  Maintain the content in a single location that all members of the team can view and keep updated.  Especially if your documentation has multiple audiences, consider using a technology that allows you to filter content for each purpose.  Creating multiple files open up the possibility for translation errors and outdated content.

An example of the vertical slice in documentation is the use of specification by example and behavior-driven development.  Illustrating use cases and test scripts up front creates a clear picture for the development team to build working software.  Using a common language like gherkin can facilitate the creation of automated test cases, connecting the quality of the code base directly back to the requirements.


Documentation requirements vary dramatically across organizations.  Regardless of the structure that you choose, using Agile principles can help you understand the document’s purpose and maximize your cross-functional team’s knowledge and time.

You Might Also Like


Overcoming Obstacles to Continuous Improvement in Your Organization

Does driving change in your organization sometimes feel like an uphill climb? You’ve tried implementing...


Responsible AI for Federal Programs

Excella AI Engineer, Melisa Bardhi, join host John Gilroy of Federal Tech Podcast to examine how artificial intelligence...