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.


Scott Sehlhorst said…
Hey Roger, one statement in your post really jumped out at me as being odd

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

Although not focused on product documentation at all, I just posted about the criticality of getting users past the "suck threshold" of as quickly as possible (

It's a critical component to releasing great software (speed of user mastery).

If your point is that great software should be so full of affordances that no documentation is required, then that's cool - I'm for that as a design goal. If not, then I would argue that everything that accelerates user-adoption is a good thing.
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".
Scott Sehlhorst said…
I think what I really find odd is my inability to capture the gist of your post from a cursory read.

When I reread, and include the quote in context, it's not weird at all.

Sorry about that - another incidence of us thinking alike.

And I agree with you that the doc is not the goal, the adoption rate is.
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

What Product Managers Can Learn from the Apple iPod

The Story When Apple unveiled its iPod digital music player back in October 2001, I dismissed it as a  parity product . I already owned the Cowon iAUDIO CW100 MP3 player, loaded with my favorite tunes. There was Apple, generating great hype over the iPod as if it were a breakthrough product. The idea of a portable digital music player was nothing new. The first mass-produced MP3 players came out in 1998. In late 2001, the concept may have been new to a lot of Apple customers, but it wasn't new to me. I proudly showed my MP3 player to friends when they gushed about the iPod. Thus Apple's iPod was not an innovative product in and of itself. Years later, however, I realized the significance of ecosystem of which the iPod was a part. Apple had released iTunes (with technology purchased from  SoundJam MP ) and created the iTunes Store for finding and downloading music. Unlike Napster , it was a safe and legal way of distributing and acquiring music. The prior way of playing

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

Interaction Design: the Neglected Skill

Your product development organization has a big, gaping hole in it. (Be prepared to feel defensive as you continue reading.) One of the most important roles in product development is the role of interaction designer. An interaction designer designs how the users will interact with the product and conceptualize the tasks they perform. He decides whether, for example, the user interface will be command driven, object oriented (clicking on objects then specifying what to do with them), or wizard based. The interaction designer decides the individual steps in the use cases. Every company has one or more people that play the interaction designer role. Usually, those people have little or no expertise in interaction design. Sadly, they typically don't even realize how unqualified they are. Let's see who typically plays the role at companies. Engineer . An engineer is an expert on building what is designed. Yes, an engineer may know how to design the internal structure of the hardware