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