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

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

Stop Validating and Start Falsifying

The product management and startup worlds are buzzing about the importance of "validation". In this entry, I'll explain how this idea originated and why it's leading organizations astray. Why Validate? In lean startup circles, you constantly hear about "validated learning" and "validating" product ideas: The assumption is that you have a great product idea and seek validation from customers before expending vast resources to build and bring it to market. Indeed, it makes sense to transcend conventional approaches to making product decisions . Intuition, sales anecdotes, feature requests from customers, backward industry thinking, and spreadsheets don't form the basis for sound product decisions. Incorporating lean startup concepts , and a more scientific approach to learning markets, is undoubtedly a sounder approach. Moreover, in larger organizations, sometimes further in the product life-cycle, everyone seems to have an opinio