Writing documentation isn’t a yes/no thing. You already know that you “should” write documentation, as opposed to “not” writing it. But this isn’t a very helpful admonition. It doesn’t tell you what type of documentation to write, how much of it to write, or how it really fits in with the rest of your project.
The most important thing to think about when approaching documentation is this:
Documentation Is Your Product
Consider these hypothetical revenue strategies for a software project:
What is the product in each of these cases?
The answer is: you never have just one product. At a minimum, for most projects: your software is a product, your website is a product, your documentation is a product. The inherent value of the software generates demand for documentation. Documentation enhances the value of the software. The website communicates with prospects and customers, and enables the distribution of software and documentation. Each component in this product ecosystem contributes to and depends upon the other two in a broadly similar way in each of these four examples, regardless of which one happens to be providing the revenue. I am not suggesting that these strategies are interchangeable, obviously they have different social implications and revenue potential, but just that the relationships between the components are similar in each case.
For each component, then, you need to go through the steps of product and customer development. Perhaps not the same specific steps, and perhaps not to the same degree, but with the same big picture of implementing features that provide meaningful benefits. It’s the system as a whole that generates revenue (or a social dividend) and in order to do this, the cost/benefit equation for each component needs to make sense.
Remember that even if something is free, it has a cost. The time required to download and read documentation, the friction of wading through difficult prose, the frustration of following instructions which turn out to be incorrect, the uncertainty of not knowing whether something will actually live up to its claims: all of these are costs which are weighing on your customers’ minds. You can usually reduce these costs considerably, and you can always reduce the level of uncertainty about these costs, leaving the customer free to make their decision on the basis of whether the benefits you’ve spelled out apply to them.
I’ve been referring to “documentation” as a single product for simplicity, but of course there are several different kinds of documentation. One of my biggest gripes with systems like JavaDoc and RDoc is that they give the impression that API reference documentation is The Documentation.
One of the most important messages I took away from Creating Passionate Users many years ago is that tutorial documentation and reference documentation are not the same, and any book that is good at one of these will not be suitable for the other. True to this assertion, I learned Java from Head First Java but since then have only used it to answer a Java question two or three times (although I have referenced the book dozens of times as an example of a superb product).
By saying that you should think of your various forms of documentation as products, I’m just filling out this idea a little more. Your “Installation and ‘Hello, World’ Guide” is one of the most important pieces of documentation you can write, but it will probably be used just once by new would-be users in order to convert them into first-time users. After this they will want to move on to some mixture of tutorials, detailed user guides, white papers, books, screencasts, developer guides and perhaps even some API reference documentation. Each of these serves a different purpose, and needs to be written to fit that purpose.
You can think about the types of documentation you need by imagining the stages of an open source “sales pipeline”:
The documentation which impacts on Step 3, for example, is “getting started” documentation which both reassures the would-be user that getting started won’t be too painful and, after providing this reassurance, actually helps them get to the “hello, world” milestone. Step 4 will be aided by more advanced tutorials and a reference guide that helps the user accomplish some of the first few tasks which they hope your software will help them with. Step 6 may involve white papers or books on more advanced technical topics addressed by your software in some way. If Step 7 is important to you, then developer documentation may be useful.
Documentation might also be important in steps 1, 2 and 5, although 1 will probably relate more to your broader marketing efforts, 2 will relate to the clarity with which you explain features and benefits on your website, and 5 probably relates most to the inherent usability of your software and its continuing feature development. Of course I’m generalizing in this analysis: your pipeline may look very different, you may will have more than 1 pipeline, and you may decide to offer various other types of documentation based on your prospective users’ needs, the time you have available, and the nature of your software.
Here is a different approach you can try, which I suspect will lead you to similar results. This is a paragraph from this great article describing writing user stories for documentation as part of an agile process:
Write user stories for documentation that parallel the user stories that are being used to build product features. An example user story for documentation might be “A DBA can read online Help to learn how to manage licenses.” An alternative is to create documentation-specific tasks that are included under the development team’s user stories. For example, the development team might have already created a story called “A DBA can manage licenses”; as the writer, you can simply add a documentation task to the story. Another idea is to house all documentation stories and tasks under a parallel project, so that you can easily estimate documentation’s velocity.
I include that paragraph as a taster, the whole article is well worth reading: Writing End-User Documentation in an Agile Development Environment
I’m hoping this post leaves you with some new ideas about what sort of documentation to write, and what processes you might want to set up around it. Future posts will talk about where Dexy fits in: how Dexy makes it easy to write robust documentation, and to iterate it in light of feedback.
I highly recommend Steven Gary Blank’s blog and also his book, on his concept of “customer development”. His ideas are nominally aimed at people selling products that cost money, but it’s well worth reading even if you aren’t looking for revenue (and as described earlier even free products have a time-cost).
Also, of course, the archives of Creating Passionate Users have a wealth of writing about technical writing.
I haven’t had a chance to delve too deeply, but it looks like there’s a lot of great content at JustWriteClick, Anne Gentle’s blog about social documentation and the source of the quote in the previous section.