Skip to main content

Holistic Requirements

Most products have some sort of documentation or user manual. Is it appropriate to include in product requirements specifications about the content of such documentation? Is there such a thing as documentation requirements?

You certainly can specify documentation requirements. Keep in mind, however, that when you do so, you may not be paying sufficient attention to what really matters to the user. (And there's some question as to whether you properly can even call such specifications "requirements".)

This issue is almost identical to whether you should document support requirements separately, or whether support is part of your product.

Ideally, a product would have no documentation whatsoever. Documentation only benefits the user insofar as it decreases the learning curve and amount of effort it takes to use the product on an ongoing basis.

A holistic view of the product treats documentation, training, and support as part of the product. When you treat the product holisitically, the requirements constrain the whole package. Thus constraints on ease of use (e.g. the amount of time it takes a user with a given skill set to accomplish functional goals) encompass the user's experience with the product, documentation, training, and support.

Holistic requirements are almost essential if you really want to satisfy the user, because they capture what really matters to the user. The user doesn't care about documentation, training, or support, they just want to learn how to use the product as quickly as possible, and for it to be easy to use thereafter.

If you specify requirements on the documentation for a product, do so only after you've captured the holistic requirements.

Comments

Roger L. Cauvin said…
Scott, thanks for the comment. What do you find odd about the statement you quoted?

Minimizing a product's learning curve ("getting users past the 'suck threshold'") is indeed critical. In fact, constraints on the learning curve should be a part of just about any product's requirements.

But there are many ways to satisfy such requirements. Good documentation can help. Good support can help. Good training can help. An intrinsically easy-to-learn product would be ideal. But these means of satisfying requirements are solutions, not themselves requirements.

A requirements analyst's job, therefore, is to specify the learning curve and to leave the decision of how to satisfy it - whether that be through documentation, training, support, or just an intrinsically easy-to-learn product - up to product designers.

When you specify holistic requirements, you include all these facets in a "black box". You constrain the whole box, not any one facet in particular. That way you don't venture prematurely into design by specifying such things as "documentation requirements".
AlanAJ said…
All aspects of the future universe are fair game, as far as I'm concerned. The test is: could it be within your control to the extent that it can be traded off in return for more function or better performance (of all kinds).

Sometimes, for example, it will be quicker and cheaper to document a quirk and its workaround, and operate that workaround, rather than resolve the problem.

Maintainability (including system documentation), for another example, is routinely compromised (= traded off) in return for more, sooner...

At the risk of making myself unpopular, though, I would argue that satisfying the user of the product is not necessarily a primary concern. The dark side of the holistic view is that the product and its users are a system with requirements. And that system's "users" can be fully satisfied (at least in theory) even while the direct product's users are deeply unhappy! Or, less contentiously perhaps, a product's users can be delighted while their "users" are dissatisfied.

Popular posts from this blog

Why Spreadsheets Suck for Prioritizing

The Goal As a company executive, you want confidence that your product team (which includes all the people, from all departments, responsible for product success) has a sound basis for deciding which items are on the product roadmap. You also want confidence the team is prioritizing the items in a smart way. What Should We Prioritize? The items the team prioritizes could be features, user stories, epics, market problems, themes, or experiments. Melissa Perri  makes an excellent case for a " problem roadmap ", and, in general, I recommend focusing on the latter types of items. However, the topic of what types of items you should prioritize - and in what situations - is interesting and important but beyond the scope of this blog entry. A Sad but Familiar Story If there is significant controversy about priorities, then almost inevitably, a product manager or other member of the team decides to put together The Spreadsheet. I've done it. Some of the mos...

5 Ways Companies Make Product Decisions

In the last blog entry, we reviewed the  four problems that companies face, or are trying to overcome, as they make product decisions .  Now we'll look at the ways that most companies make their product decisions. Companies that develop, market, and sell products and solutions make strategic and ongoing tactical decisions.  They decide what features to include in their products, what messages they will use to communicate the value of their products, what marketing tactics they will use, what prospective customers they will target, and many day-to-day choices. Whether or not these decisions are deliberate or ad hoc, most companies use some combination of the following ways of making product decisions. (A downloadable "map" that summarizes the product decision landscape is included at the end of this article.) Customer Wants Product decisions based on feature requests, focus groups, and what prospects and customers say they want. Companies are selling products to ...

Is Customer Development Pseudoscience?

The “Science” of Lean Startup Lean startup practitioners embrace the scientific method, seeking the "truth" about what business model and strategy will lead to product success. We do so by: Formulating hypotheses Crafting and running experiments to test them Learning from the experiments Iteratively feeding our learnings back into revised hypotheses Sounds pretty scientific, at least in spirit, doesn't it? Yet this process actually neglects a key ingredient in the scientists' mode of operation. To identify what’s missing, let’s examine “customer development”. Customer Development Steve Blank is one of the pioneers of the lean startup movement. He introduced into the lean startup lexicon the term “customer development”. Customer development consists of sessions and interactions with customers to test hypotheses. For example, a product manager might interview a prospect, asking if she agrees with the product manager’s hypotheses about the problem...