Agile Requirements Documentation
Agile Requirements DocumentationJust because we're doing ExtremeProgramming or some other form of AgileDevelopment doesn't mean we would not like to have some kind of official requirements document. It does mean, however, that such a requirements document is not strictly required for communication within the development team. We should, therefore, consider the expected audience for the requirements document lest we create a DocumentThatNobodyReads?.
The following discussion does not yet identify the audience and purpose of the proposed requirements document. I believe that omission is the cause of some of the disagreement. It is difficult to determine the worth of a proposed solution without first defining the problem to be solved.
A good requirements document allows us to say what we assert that the program does, and gives us something to compare against to confirm that it does what it should. It also gives the customer a way to check what the program already does when deciding how to use the software to meet a business need, and deciding whether the program needs additional functionality to meet a business need.
Since we develop the requirements incrementally in AgileDevelopment, the official requirements documentation should also be developed and maintained incrementally. Furthermore, there must be some way of identifying which version of the document is supposed to reflect which iteration of the software. This process must work correctly even though the documentation might be updated first, and a feature for which requirements have already been formally documented may end up being deferred or canceled.
Finally, whatever is used to do this must be light-weight. In fact, it may be fine to omit this kind of documentation altogether on some projects, and on others, it may be OK to defer the formal documentation component until a strong need for it is identified. It should be possible to produce the document at this point by reading and summarizing info from the programmer tests.
Tools:
Clearly, if a formal requirements document is to be maintained, MS Word is not up to the task, so what to use?
Why not MS Word? Word has built-in version control and diff, lets you embed graphics and hyperlinks to anything. You can even place a link to run the latest build.
I routinely use Word with embedded Visio diagrams for the UML and other line art, embedded screen shots, and links to prototype web pages, source code and reference materials. This is without using VBA which will let you script anything else you need.
What's missing?
Agreed. YetAnotherTool? is hardly the answer, especially for a small team that really doesn't have the resources to research or learn additional tools unless really necessary. Everyone can use MS Word.
I typically put all of my requirements in a big table, then make other columns to identify shall/should/could, assignment, reference, and one or two other things that make sense for that project. This is good enough, which is what this agile stuff is about anyway.
How about MS Access to store requirements? This was an option we were considering on my last project due the unwieldy nature of requirements in a giant, multi-file Word document and an Excel cross-reference document mapping requirements to design, test, releases, etc. It was quite straight-forward to extract Access into various Excel documents as needed, but we did not get around to addressing how to generate a Word document in our customer's desired format (or seeing if we could get a waiver and just deliver an MDB file). Also, we didn't relish the task of retyping the current requirements document from Word to Access. We didn't carry the idea to conclusion, but I'll leave it here in case someone else wants to run with it.
You can use almost anything, but it doesn't help your agility. Storing requirements is not necessary for software development, though it may be necessary for the business requesting the software development. If it's not required for software development, it's not a necessary part of the software development process. If it's still needed, it's a business requirement and the requirements documentation should be stored in the way the business wants. You may probably find it more agile to create that documentation format after the fact, rather than maintaining it throughout the project.
Whoa, take it easy! I am not making any statement regarding the intrinsic value of requirements documentation, I am merely saying that if it is required by the customer, then one should consider how to make the generation of requirements documents as agile and efficient as possible. Rather than writing directly in Word or Excel or what have you and trying to keep multiple documents synchronized especially in a large, multi-release schedule, consider keeping the requirements text in a central format and use that to generate the final text in the desired format. My understanding of agile development is that the intent is to allow the customer to determine what deliverables are desired; it is not up to the development team to make value judgments on the customer's requests. Once the customer has decided on a deliverable, however, the development team is free to determine the most effective means to deliver it, and agility applies just as well to writing documentation as to writing software code.
Let's consider this assertion, that storing requirements is not necessary for software development. There can be no argument that communicating requirements is necessary for software development. And SoftwareDevelopment is bigger that programmers writing code - it also involves testers writing and running tests, documenters and trainers writing documentation and giving training for users, and decision makers making decisions (i.e. requirements) about the characteristics of future releases given the characteristics of past releases - repeatedly, over the lifespan of the software. Assuming efficiency and effectiveness are at least desirable, if not necessary, then what is more efficient and effective - storing requirements in a container other than people's memory, or repeatedly and redundantly and inconsistently communicating them from the stores of people's memory? --RandyStafford
Randy, I'd like to remind you that this page is about AgileRequirementsDocumentation.
I believe the question of efficiency and effectiveness is the correct one to ask. Is writing a requirements document the most effective and efficient way to capture and communicate the needs and desires of the eventual users?
Software requirements are the generalization of specific instances of actions taken by a multitude of people in a multitude of environments. When reviewing written requirements, it is almost impossible to identify what necessary information is missing; the users assume this knowledge is known and the requirements analyst is unaware of it. It is very difficult to write non-ambiguous or identify ambiguous requirements; the assumptions made by users, developers, testers, etc. can lead to differing interpretations of the same text. Written requirements are rarely prioritized; they are listed as an all-or-nothing set precluding early use of key subsets. Finally, it is difficult even to identify incorrect requirements once user operational flows have been decomposed into a mind-numbing list of stand-alone statements.
The alternative? Successive approximation. Talk to the users, quickly develop a small amount of code based on those conversations, then have the users evaluate the result. This is effective, as it reduces the number of layers of communication and quickly identifies misunderstandings by getting the result into a real world evaluation. If one looks closely at this approach, it mirrors the traditional approach of requirements gathering, but allows evaluation based on actual use, rather than evaluation of written text that relies on mental models stored in various people's heads.
The effectiveness and efficiency argument comes down to a trade-off between the cost of high levels of communication directly between users and developers and the time needed to get to specific levels of service provided to the users.
-- Wayne Mack
Wayne, what does your alternative have to do with agile requirements documentation? I need no reminding of what this page is about. I simply took issue with the assertion that storing requirements is not necessary for software development. In my experience storing requirements is necessary for software development. And I take issue with alternatives suggesting that requirements be stored exclusively in source code. The reality is that product managers, testers, documenters and trainers, and buyers and users don't read source code to learn what decisions have been made about a system's characteristics. Again, developers are not the only consumers of requirements information.
The question is, what are "agile" ways to document requirements. Which begs a characterization of "agile". Personally, I prefer AlistairCockburn's characterization in AgileSoftwareDevelopment - "light but sufficient". In my experience in software product organizations it is insufficient, for a quality product and an efficient, effective process, to have no requirements documentation. Even CrystalClear, an agile methodology for the smallest of teams working on the most inconsequential of systems (in AlistairCockburn's characterization of projects), describes some six "requirements" work products.
When it comes to a "light", but sufficient, medium for capturing these work products, I like wiki webs. The hypertext, collaboration, and page history features are well-suited to the purpose.
EditText of this page
(last edited February 3, 2011)
or FindPage with title or text search