6

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?

Improve this question
7
  • 2
    Why do you think that there is a need for requirements to be documented outside of the set of completed user stories (and the associated acceptance criteria)?
    – Thomas Owens ♦
    Jan 5, 2017 at 17:38
  • In other terms - what value is added by maintaining your requirements in two different tools or formats? First, consider value to external parties (customers, users). Second, consider internal value. Then, consider the effort needed to create and maintain your requirements in two places. Keep in mind that you want to have a single source of information.
    – Thomas Owens ♦
    Jan 5, 2017 at 17:58
  • @ThomasOwens I totally agree that there should be a single source of information, hence this topic :). As stated, higher ups at my company used the BRD which was the defacto "requirements doc" for the project as basically a contract the client and we were agreeing to. I don't think individual users stories would be formal enough for their satisfaction nor do I think they'd be willing to use a tool like Rally (not that that's acceptable).
    – mellis481
    Jan 5, 2017 at 20:06
  • So if user stories + acceptance criteria are insufficient, why are you using them? There's nothing that says that you can't use a formal requirements specification in any of the agile methods.
    – Thomas Owens ♦
    Jan 5, 2017 at 20:08
  • @ThomasOwens It's not the content of the user stories + AC. It's their location; in an online tool a manager may not be familiar with, separated by individual story. I'm comparing this to a BRD that is a single, ubiquitous Word document.
    – mellis481
    Jan 5, 2017 at 20:15

2 Answers 2

Reset to default
5

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.

Improve this answer
1
  • That's a bit of an over simplification. It's an issue of seeing the forest from the trees. Usually project would benefit from some form of high-level documentation that is more of a strategy rather than tactical. Jira comments are just tactical in nature. One of the weaknesses I noticed from having too short of a Sprint cycle is that projects will actually meander over time. Fundamental problems will be left unfixed in pursuit of short-term goals.
    – Chris
    Feb 15, 2017 at 14:37
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.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.