What makes a good requirement document for an agile project

Jason Sendelbach

As a developer, I start from requirements. I have worn project management and business analyst ‘hats’ on many projects (but I am a geek, as I really enjoy the developer hat the most). My coworker, Alice Toth, has come up with a pretty awesome template and style of writing requirements that seems to be perfect for the agile development methodology. Too often, I see struggling projects struggle, because their requirements suck. I look at their “requirements” and they are nothing more than a picture with a bunch of notes. The developers have so many questions, and in general, all people involved (client, developers, BAs, IAs and testers) don’t have a good understanding of the system as a whole, and what are the various personas that use the system.

I have worked on projects that have used Use Cases and Functional Specifications, but these never seem to convey all the necessary information for all involved. They tend to be very verbose, and they are really not fun to write, read or manage. A good requirement should tell each audience member exactly what the expected functionality is, and never generate a myriad of questions from all involved. It’s often difficult to solicit information from a client, but documenting for developers should never be that hard. Here is a recap of what a good requirement is:

Good Requirements:

  • User Stories
  • User Acceptance Tests
  • Workflow
  • Requirements (Details)
  • Wireframes

Without any one of the aforementioned sections, the requirements start to lose value. Each section brings a lot to the table, and too often they are judged as a “waste of time.” Much like pair programming, having each of the sections for your requirements actually creates a synergy, as the development process is sped up. (Sorry for the consultant buzzword, but it does)

Download FDA Agile eBook

User Stories

This states all of the scenarios of the users involved. These should read:


The user stories are critical to lay out exactly who is going to do what, and for what reason(s).

User Acceptance Tests

These should include all scenarios outlined in the user stories. These should not be too detailed (they don’t need to mention specific screens or a complete list of actions to execute the steps). These should read:

GIVEN that condition 1 and condition 2….
WHEN I do step 1, and step 2…
THEN, desired result 1, desired result 2….

These define a set of actual scenarios a tester could walk through to assert that the feature is complete. These are not detailed test scripts that you find in UAT. They are meant to convey a set of tests that all involved can walk through to understand how the feature will work.


This should include a picture of the screens involved. Error states and view changes based on role should be documented. This picture is worth a thousand words, as the details of the flow through the feature can be quite complex, and this is hard to spell out the details in the next section. We have been using Gliffy, a confluence plugin, and it rocks. It is a flash app that allows us to create and edit the workflows with eases.

Requirements (Details)

These are the details of the feature. Document all screen(s) and every field, label, validation, message, and action. This is essentially the functional specification of the details of the screen(s) involved. Because it is in the context of the wireframe (next section), it is more concise. You can simply reference the field name, rather than verbosely state everything about the field. You can keep the details to field length, required, etc.

A picture is required for each screen involved. Wireframes can be simple drawings on a whiteboard that are photographed or a set of boxes created in Visio or OmniGraffle (or anything really). Some are photoshop-ed, and others are HTML. We have found that the best approach is HTML if that’s your end result. Recreating HTML that looks the exact same as a picture can be quite painful. Usually, a visual designer is involved in creating the mock-ups, and can easily do this work in HTML. The developers can, therefore, take the exact HTML that is requested, and fill in their code as needed.

See Alice’s post about wireframes, and Noel’s post about how you can allow a designer to write the HTML within a rails application.

Smooth Project

If each iteration begins with all features fully documented in this format, it runs smoothly, and often finishes early, leaving time for those TODOs we all keep a list of. I have found that when writing requirements in this format, many of my questions for the client comes from writing the very first two sections. Coming up with the user stories and acceptance tests often find huge oversights of the feature, as you start to detail who will use it and in what ways.  This is especially useful for software solutions such as Software as a Medical Device (SaMD) where achieving clarity around what is a properly functioning application is a regulatory requirement and prevents accidental harm to the health of humans!

Given that I am a user who clicks on a link…. well – what if that user doesn’t have access to view the link? Details like this help generate a list of questions for the client, who often can’t think that far ahead with respect to the complexities of the system. Writing the requirements to this level of detail ensures that oversights are found early and before any code is written. Unfortunately, all too often, some project managers don’t see the value in ensuring requirements are complete before they get the developers involved. This always leads to chaos during the iterations and is a recipe for disaster. I have found that projects that have finished requirements before iterations are often under-budget, and the team members are quite happy to be on the project.

Related Posts


End of the Line for EUA: Are You FDA Ready?


TINY GVS: Reimagining the Validated State


Cloud Computing & Validation: 6 Key Recommendations


The Validated State: MedTech’s Standard of Trust