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 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
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:
- Schedule a series of lunches with the product manager.
- At the first lunch, ask about product goals, target market, and problems.
- 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.)
- At the third lunch, get some details on delivery frequency, localization, and backwards compatibility.
- Take a break to write a draft Agile Requirements Document. Send it to the product manager.
- 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.