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

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 (http://tynerblain.wordpress.com/2005/12/14/getting-past-the-suck-threshold/)

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

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

Use Case as a Black Box

Consider the following use case: Purchase Items Actor: Purchaser Precondition: Purchaser types at least thirty words per minute and has a web navigation efficiency rating of at least 40. Postcondition: For the average Purchaser acting at full efficiency, the number of seconds elapsed is no more than 30 + 20 * n, where n is the number of items purchased. The name of the use case represents a functional requirement. What does the product do, or enable the user to do? Purchase items. What are we to make of the preconditions and postconditions? What relationship do they have to the requirements for the product? Answer: the preconditions and postconditions are the nonfunctional requirements attached to the functional requirement . Another way of expressing the nonfunctional requirement would be as an attribute and associated constraint: Usability: For a Purchaser who types at least thirty words per minute and has a web navigation efficiency rating of at least 40, it shall take no

Henry Ford's "Faster Horse" Quote

You may have heard the ( apocryphal ) Henry Ford quote: If I'd asked customers what they wanted, they would have said "a faster horse". Over at the On Product Management blog , Saeed gives his take on this infamous quote. He "hates" it, and gives some compelling reasons. Saeed is spot on in his explanations. Personally, I think the quote is great, but it's a matter of interpretation. The valid point of the quote is not that it's a bad idea to facilitate a conversation with your market to better understand it. The valid points are: You must ask the right questions to get valuable answers. You must interpret the answers thoughtfully - often outside their direct meaning - to glean reliable information. Asking questions is not always the best way to "listen" to your market. (E.g., sometimes pure observational studies are more reliable.) Nonetheless, I find the quote is helpful to combat "armchair product management" in the