Yes! Expect or Write an “Agile” Requirements Document

By Eric Kuhnen, Focal Partners, special to The Content Wrangler

Mike Wethington, Certified Scrum Practioner, runs the Agile Development and Technical Communications forum inside The Content Wrangler Community. One poster in that group recently expressed the following regret:

“I think the Agile, iterative approach is great, but I miss the up-front, fleshed-out spec that gave me the full picture early in the project.”

image The quoted poster (above) hints at a truism: documentation managers cannot guide their teams effectively when product management is in anarchy.  When documentation managers have a complete picture of the product, they make better choices in planning documentation planning phases about what to write, how to cross-reference it, when to use examples, what facts to double-check, etc.  When anarchy reigns, announcements of new product features are known perhaps two weeks before the documentation is due.  Documentation teams kiss their loved ones good-bye and start writing.  So, when an Agile product manager says that there will be no more product requirements documents because the company has adopted Agile, documentation managers understandably get a little jumpy.

Somehow, in the rush to adopt Agile principles for software development, some product managers have overreached in their interpretation of how “agile” they should be.  Indeed, at a recent conference I attended (the P-CAMP Unconference for Product Managers put on by Enthiosys), some attendees were arguing that adopting Agile meant tossing out the venerable product roadmap, too!  Fortunately, cooler heads prevailed, pointing out that product roadmaps have several perspectives, depending on the audience, and that Agile product managers should build roadmaps that take many factors into account, not just the sequence of planned feature releases.  In the same way, documentation managers should expect “Agile” requirements documents from their product managers.

Traditional Requirements Documents

Documentation managers usually receive either or both of two kinds of requirements documents.  The first is the Market Requirements Document (MRD), which spells out details about target market segments, planned revenue, sales strategy, but also has information about usage models, required features, and backwards compatibility.  The whole purpose of an MRD is to distribute information about the next release to everyone who contributes to the product delivery program, including executive management, usability specialists, product marketers, documentation writers, engineers, and testers.

The second is the Product Requirements Document (PRD).  A PRD specifies such details as functionality, compatibility, internationalization, dimensions, weight, etc.  Few executives are interested in the details found in PRDs, but they are loved by usability specialists, product marketers, documentation writers, and testers because of the wealth of information about what the product should be able to do.

The problem with MRDs is not what they contain but when they’re written.  Most companies are still using the Waterfall development model.  Waterfall requires the establishment of market requirement, product requirements and software designs well ahead of implementation and release activities.  It is not uncommon for an MRD to be a year or two ahead of the final release, which requires the product manager to see far enough into the future to anticipate new technologies and competitor capabilities.  Such foresight is rarely possible, so the MRD boils down to educated guesswork, and its utility to documentation managers is limited once the PRD is written.

The problem with PRDs—and the reason product managers claim that they’re obsolete under Agile—is that PRDs often contain design-level information.  Why?  Two reasons: one, the product manager is a converted engineer so he thinks he knows what he’s talking about.  Two, the product manager doesn’t trust the engineer to build the thing correctly (a common issue with user-interface specifications).  There may be other reasons, but the result is that a PRD winds up with too much design-level detail.  Of course, documentation managers like to have this kind of information because it simplifies or eliminates certain conversations with developers later on.  But engineers detest this kind of detail in PRDs because, come on, if the product manager were really that good at software design, he would have never gone over to product management in the first place.  What’s more, product managers find PRDs to be tedious exercises because it takes so very long to write down all of the functional and design requirements to a level of detail sufficient to banish any ambiguity.

So, the newly “agilized” product manager declares his freedom from the tyranny of PRDs, stops writing them, and leaves the documentation manager with little of the “up-front, fleshed-out spec that [gives] the full picture early in the project”.  The result?  Read the following snippet from Joel Spolsky’s excellent October 2, 2000 column entitled Painless Functional Specifications:

“When you don’t have a spec, what happens with the poor technical writers is the funniest (in a sad kind of way).  Tech writers often don’t have the political clout to interrupt programmers.  In many companies, if tech writers get in the habit of interrupting programmers to ask how something is supposed to work, the programmers go to their managers and cry about how they can’t get any work done because of these [expletive deleted] writers, and could they please keep them away, and the managers, trying to improve productivity, forbid the tech writers to waste any more of their precious programmers’ time.  You can always tell these companies, because the help files and the manuals don’t give you any more information than you can figure out from the screen. When you see a message on a screen which says, ‘Would you like to enable LRF-1914 support?’ and you click ‘Help’, a tragicomic help topic comes up which says something like, ‘Allows you to choose between LRF-1914 support (default) or no LRF-1914 support.  If you want LRF-1914 support, choose ‘Yes’ or press ‘Y’.  If you don’t want LRF-1914 support, choose ‘No’ or press ‘N’.  Um, thanks.  It’s pretty obvious here that the technical writer was trying to cover up the fact that they didn’t know what LRF-1914 support is.  They couldn’t ask the programmer, because (a) they’re embarrassed, or (b) the programmer is in Hyderabad and they’re in London, or (c) they have been prohibited by management from interrupting the programmer, or any other number of corporate pathologies too numerous to mention, but the fundamental problem is that there wasn’t a spec.” [emphasis added]

The “Agile” Requirements Document

What a documentation manager needs—and should expect from the product manager—is an “Agile” Requirements Document.  This is not an oxymoron.  An Agile Requirements Document gives the documentation manager enough information to understand where the product is going, what purpose it should serve when it gets there, and how it relates to the world around it.  It doesn’t answer every possible question within those three areas because the document—like the organization that produces it—is agile; some of the details have not been worked out.

Here is the minimum set of items that an Agile Requirements Document must contain:

  • Product Goals—A clear statement of objectives the product will achieve when it’s mature and functioning correctly.  NOTE: the first product release likely will fall short of the product goals.
  • Delivery Frequency—How often the product team will send a new release into the market.
  • Target Market and Problem—A generalized description of the kinds of customers who would buy or otherwise acquire the product.  Also, clear statement about the kinds of problems found in this market for which the product is a solution.
  • User Personas—A set of fictionalized users of the system, complete with name, background, skills, environments, attitudes, behaviors, goals, etc.
  • Use Models—Multiple examples (3 or more) of how the product will be used in the real world; also, key tasks that will be performed with the product.
  • Localization Requirements—The set of languages into which the Help and UI will be translated.
  • Backwards Compatibility—A statement of tolerance for earlier versions of the product.  NOTE: some will question the utility of this particular item, but my experience over the years is that documentation writers will be sympathetic to their readers if they know whether or not the reader is being forced to “relearn” the product because of incompatibility with a previous version.

If the document contains any of the following items, all the better: positioning statement, feature/benefit summaries, unique selling proposition, areas of competitive differentiation.  However, absent these addition details, the Agile Requirements Document is a kind of guiding star of relatively unchanging information.  Few product managers will change any of these details between iterations of an agilized product.  For example, if a company was selling rock-crushing blenders into the commercial food preparation market, it would be highly unlikely for the product manager to change the product goals week to week, or even month to month, without an accompanying shift in company priorities.  No documentation is so far out of the loop as to miss that kind of alteration!

A document containing the foregoing mandatory items is indeed “agile.” It places a premium on individuals and interactions (vis-à-vis several of the required items).  Furthermore, it gives room for the product manager to respond to changes, but the changes are almost always within a broader context so that documentation managers don’t wonder about the overall direction of the product.

Use Models and User Stories

An Agile Requirements Document is also “agile” because the use models have at least some element of customer collaboration in them.  Use models are helpful in conveying general capabilities in the product (e.g., making flight reservations or ordering socks) along with how the product will be used (e.g., on a handheld computer while zipping through traffic).  Unless product management really misread the market, use models don’t change very often.

Nevertheless, documentation managers need more information than an Agile Requirements Document alone can provide.  They also need copies of the user stories that the product manager has given to the developers.  User stories are statements of expected behavior (i.e., as a , I want so that I can ).  They aren’t perfect, but they often reflect exactly what the customer wants out the product, which is ideal input for documentation managers.

One limitation of user stories is they do not specify how a capability is implemented.  Some documentation managers, particularly ex-programmers like me, feel a compelling need to have the “how it’s done” information in hand.  The root of that need is spotty communication with the development organization; knowing how something is implemented saves discussion time and builds domain expertise within the technical publications group.  If at all possible, this need to know “how” should be tempered by a desire to know “why”; why does the software do this; why does the product install that way.  In the final analysis, the customer doesn’t care how a thing is built so much as she cares about why it does this thing or that thing in response to a set of inputs.  User stories go a long way toward answering “why” questions, and are therefore preferable to detailed specifications on how a thing is implemented.

Getting an Agile Requirements Document from Product Management

Getting a product manager to deliver an Agile Requirements Document may seem like pulling teeth from a hummingbird.  These folks move around a lot and they may come back with the misguided “we’re Agile now so no specs” routine.  And if the documentation manager doesn’t have a good champion in his senior management chain, his group may be walking into situation where there are literally no specifications to guide them.  At this point, the documentation manager needs to write the Agile Requirements Document.  Fortunately, it’s easy and probably deductible as a business expense.  Here are the fine points:

  1. Schedule a series of lunches with the product manager.
  2. At the first lunch, ask about product goals, target market, and problems.
  3. At the second lunch, discuss use models and user personas.  Make this as long a lunch as possible.  (I recommend Italian food; it can’t be rushed; it’s delicious; and it invites conversation.)
  4. At the third lunch, get some details on delivery frequency, localization, and backwards compatibility.
  5. Take a break to write a draft Agile Requirements Document.  Send it to the product manager.
  6. At the fourth lunch, have the product manager give feedback on the draft.  Put the lunch on his tab.

The preceding lunches will work.  The documentation manager gets a specification; the product manager discovers a colleague.  If the product manager has taken time to write a full market requirements document, the documentation manager can strip out only what is necessary and then ask questions in just one or two lunches.

The key point in all of this is that an Agile Requirements Document is an absolute necessity.  Getting the user stories themselves is fairly easy; the product manager has them written down in her product backlog.  But the Agile Requirements Document may not exist.  And the documentation manager who thinks of her organization as a strategic asset will stop at nothing to obtain one.

So, expect to have an Agile Requirements Document, one way or another.

About the Author

Eric Kuhnen is Managing Partner at Focal Partners. He can be reached at

Tags: , ,

8 Responses to “Yes! Expect or Write an “Agile” Requirements Document”

  1. Virginia O'Connor March 31, 2008 at 2:34 pm #

    Eric, again an excellent article, but in my opinion, you’ve missed one point … agile teams working on the product storied need to include more than the architect and the developer and the tester – the ideal team involves the writer too (sometimes the marketeer too). This is not a common business practice from what I’ve seen, don’t get me wrong. Many companies organize their writers in one team and the development/qa on another – sometimes going so far as to separate them by large distances.

    As a technical writer who works on an agile development team, this old pattern is a big mistake.

    The writers bring far more to the development effort than simply a noisy voice trying to write the end user-facing documentation. When involved in the story from the beginning, they bring a user face to the elaboration of the feature. In the absence of a user-interface expert, the technical writer is often the next best option for input into the screen design (having often worked with a larger scope of the product than the developers themselves).

    Because they are involved in the elaboration, the writers understand the ‘why’ of what this feature is about, which drastically improves the quality of the content and moves it from the amateurish attempts of this does this and that does that (plus a glossary and a shortcut key map). Plus, there are fewer questions to ask the developers because the opportunity to understand the feature’s functionality occurred through elaboration.

    You are spot on with your recommendations to documentation managers, I agree, but the key to a real working agile team is to involve all members of the team – writers included. It’s the first question I ask when I interview for a job, and I try not to work with or for companies who do not recognize this very crucial detail. The writers are part of the team, not the afterthought.



  2. Mike Wethington April 1, 2008 at 3:41 pm #


    An excellent article. I think you make a clear and logical case for an Agile requirements document. I especially like your DIY approach when all else fails.

    At my company (a start-up), doc is involved in the process from stage 1, roadmap roll-out. This being said, we often do not get the ‘classic’ Agile requirements document for our quarterly release. However, we have been trained (like a puppy getting its nose swatted) to pick up on much of the requirements in our revision planning sessions.

    The culture at my start-up is everything from cocktail napkin specs to good classic Agile design docs. The key to success in either case is for the roadmap to be well defined and the goals/themes of the release be well communicated.

    If you can get those, and if the Dev Manager doesn’t have them the project is doomed anyway, you have a shot at delivering doc that satisfies the 80 of the 80/20 rule.

    Virginia, it looks like you’ve been reading my notes for my STC presentation in Philly.


  3. Virginia O'Connor April 1, 2008 at 3:45 pm #

    Mike, I haven’t been reading them, but it’s good to know you face some of the same issues. Good luck in Philly!

    Will the presentations be available online, do you know?


  4. Mike Wethington April 1, 2008 at 3:59 pm #


    I’m not sure if the presentation will be online (I think that’s up to the STC) but I am planning on putting a modified (and expanded) version on the web. Probably on this website or on the Agile Alliance website (I’ll link to it from here).

    It’s hard to condense 60+ slides into 15 for a 45 minute presentation.


  5. Eric Kuhnen April 1, 2008 at 7:08 pm #


    A very thoughtful response.  I agree that writers should be part of the team.  By way of explanation, the thrust of this article is the need for a spec, which some Agilists repudiate as outdated.  The focus of my thoughts was on how such a spec would be written, and so I wasn’t thinking about team composition.  Your point, though, is a good one and could be the subject of a subsequent article.

    To illustrate your point, I could cite the experience I had with one client who included the Documentation Manager as the focus of a few user stories.  It was remarkable how the design of the product was improved by adding that consideration.  To make this a repeatable event, writers would have to be part of the team from the beginning in order to contribute those stories to the product backlog.

    The more I think about this, the more I like this for an article.  Great suggestion!


  6. Eric Kuhnen April 1, 2008 at 7:11 pm #


    You raise some good points about the benefit of a well defined roadmap.  Documentation managers should insist on this point, and a good ARD (Agile Requirements Doc) should map to it.



  7. Virginia O'Connor April 2, 2008 at 11:43 am #

    Yes Eric, I understood the thrust of your original piece and I sincerely agree. The spec is being abandoned at an alarming rate and I’m glad you’ve pointed that out.

    I am glad, however, that you are also considering the ‘include the writers’ angle as well because I think this is a significant problem. I have seen how the writers bring that extra voice/perspective into the elaboration – often the user’s voice to the best of their ability – and it enhances the feature tremendously. Plus, often the writers are the best at distilling the decisions made into a follow-on message that is redistributed through the team to add to the story’s development.

    I feel that all sides benefit from the writer involvement, and I’m curious if you publish this article whether there is disagreement.

    Could be interesting … have fun with it and I’ll be here to watch/contribute!


  8. Gordon September 24, 2008 at 8:05 am #

    I was with you right up until you suggested the “if you Product Manager won’t write, the Documentation Manager should…”

    Define “product” please. Do you mean “software”?

    If not then the Product Manager is, ultimately, responsible for the entire product and if he/she fails to provide the inputs the Documentation Manager requires (be they whatever format) then he/she is presuming the product needs no documentation.

    Ok, this is an overly simplistic view but I can envisage the Product Manager quickly catching on to the fact that if they don’t produce such a document… hey look the Documentation Manager does it for them!

    Personally, I don’t have the time and I have plenty of other things my writing team can work on.

Subscribe To Our Newsletter

Join our mailing list to receive the latest news and updates from our team.

You have Successfully Subscribed!