Sunday, 9 October 2011
09:17 PM
Let's say you have a new product coming out. When do you need to have the documentation ready to ship? Many of us came up in documentation in the era of shrink-wrapped software, which generally included hard-copy documentation. In those cases, obviously you shipped the documentation when the product went out the door. Your next opportunity to update the docs was the next release of the product, in the box.
Even as documentation became a web-based resource, however, the mentality persisted in some quarters that when a new product came out, a complete set of documentation had to be available. Not true. Consider a typical (or probable) adoption curve for your product:
(Please note: this is a made-up diagram; it does not represent any actual data or actual users or actual products.)
My intent here is to illustrate that we release a product and sometime after that initial release, we might send out a bug fix/service pack release to tweak issues. At some point we'll generally come out with a "point release" that fixes more bugs and introduces some new minor features, and then at some point we come out with the 2.0 version of our products.
Early adopters will start playing with the product as soon as we release it. But we've found that many people don't really dig into a new release until well after its initial release, often not till a point release. And we're no longer surprised to learn that late adopters can be (at least) a full version behind our current release. (This is not just because they're hesitant; at large companies, for example, adopting or updating a major technology is a non-trivial task that can cost millions and is not undertaken lightly.)
Update 26 Oct 2011 Just found a fascinating article on how Volkwswagen still today is standardized on (and requires) Internet Explorer 6, a browser that's over 10 years old.
Ok, back to docs. Given all this, what do we really need to have available the day that our product hits the (virtual) shelf? Obviously, this is going to be different for each product, but this is the sort of thing that we generally consider important to get the early adopters up and running: - Introductory tutorials.
- API reference for the most important programming interfaces.
- Blog entries from experts (internal and external).
- For the 2.0 release, a "What's New" guide.
The thinking here is that early adopters often already have some background knowledge and are ok using cutting-edge products. Our focus is to make sure they have enough to get up and running.
After the initial release, we can concentrate on additional documentation, including:- End-to-end scenarios.
- In-depth conceptual overviews that introduce new technologies; this is often the type of information that early adopters either already know or can glean from scattered sources like blogs.
- How-to articles for specific tasks that we know users will need.
By the time a point release comes out, there's likely to be one or more third-party books for the product as well.
As we approach a 2.0 release, we can consider rounding up some of the following types of documentation that will be useful:- Case studies that highlight the product in real-world scenarios.
- Architectural and design guidelines.
- "Deep dive" documents that get into non-mainstream scenarios.
- Migration guides, both from the 1.0 to 2.0 version of our product and (if available) migration from a competitive platform to our product.
- Performance and optimization guidelines. (These typically require some real-world experience with the product to identify the bottlenecks and gotchas.)
In fact, we might not create most of these, but as they become available from reputable sources, we can add links to this information into our documentation at appropriate points. By this time, we'll also probably have a pretty good idea of what documentation we might never have to provide officially, either because we can see that people don't need it or because it's adequately covered elsewhere.
The point here is that you need to understand the product adoption cycle for your product and plan documentation accordingly. What have you found about your own adoption cycles and documentation requirements?
Update 10-Oct-2011 Language edits.
Update 11-Oct-2011 I remembered another category of docs that fits into this timeline, but in a slightly different way. See my next post for more info.
[categories]
writing
|
link
|