Feature Article

Saturday, March 29, 2008

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.”

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 ...

Read more

Related article: Excellent and Consistent Content Development through Agile and Scrum

Filed under: Agile Development : Technical Writing : Requirements Documents

News & Notes
(updated daily. almost.)

News RSS Feed