Documenting requirements on an Agile project

Question

One of the values of the Agile Manifesto is "working software over comprehensive documentation". And yet there is a need for requirements to be documented. If a feature developed 6 months ago is being altered, I (as a developer) need a place to go to to reference the existing requirements. Documented requirements are obviously important for QA resources as well. Also, if a question arises about a particular requirement, there should be a single location one can reference for clarification rather than requiring me to parse through my code or a string of emails to see how things where built.

The Agile teams I've been on have all used an online management (eg. Rally, Jira) where requirements can be defined under each user story as acceptance criteria. While I find this to be an extremely functional solution/location for requirements documentation since you're constantly using the tool to move the story along, it seems a little informal. On the most recent project I worked on, the project management team maintained a BRD (Business Requirements Document) which contained all system requirements in a single document. On this particular project, the BRD was used for sign-off from the client on what was going to be developed and was also reviewed by my (consulting) company's management team to ensure everything was completed. The issue with BRDs in my experience is that they're verbose to the point of unreadability.

The Agile framework does not concern itself with defining a specific means of documentation, but is there a single best practice for documenting requirements on an Agile development project?

Answer 1

There are three agile principles that are at play:

1. "Working software over comprehensive documentation" from the Agile Manifesto.
2. "Simplicity--the art of maximizing the amount of work not done--is essential." This is one of the Principles behind the Agile Manifesto.
3. The Single Source of Information from Agile Modeling, which brings together various techniques and principles for designing and documenting software in an agile environment.

Maintaining requirements in a tool like Rally or JIRA in the form of user stories + acceptance criteria and simultaneously in a requirements document is inherently not agile. You are creating excess documentation, failing to maximize work not done, and you have multiple sources of information that need to be maintained (and may become out of sync with each other).

The only solution is to maintain your requirements in one location. If your team is using a tool now and some stakeholders aren't comfortable with that tool, you have two options. The first option is that your team can adjust its process to make all of the stakeholders comfortable. The second option is that your ScrumMaster or Agile Coach can educate the stakeholders as to the value

There is nothing that says that an Agile project can't create and maintain a requirements document in the form of a spreadsheet or Word document and work from that. After all, good requirements (among other things) specify importance to allow prioritization, are verifiable and can be linked to the information needed to test them (even if it's not all available in one tool or document), and are traceable to other work (likely be ID). If you have a requirements specification, your team can still trace work tasks, test cases, or acceptance criteria to items in the BRD via the unique requirement identifiers, for example.

Answer 2

The Agile thinking suggest the best practise is to document just enough. If you need to document something for a good reason, document it!

In software development each project has its own needs, there is not a single definite source of truth. For some teams or projects automated test-cases are enough documentation. Some need a more formal way like user-stories in a workflow system, instead just on index-cards.

BRD's do sound like over-documenting and a way to have command and control over the development team by the client, but if it works for the project and team its not perse anti-agile.

The Agile framework does not concern itself with defining a specific means of documentation

Most Agile frameworks do not specify anything, except to be value driven and work in iterations and of-course the other principles. Overall its a mindset. Frameworks that do specify everything are focusing on processes and tools over individuals and interactions. Question how Agile that framework really is.

Find a way of working that fits your industry, company, project or product. Inspect and adapt continuously, this way you will find the optimal way of working eventually.