This document describes the overall vision of Puppet's documentation. It is targeted largely at the structure and flow of the documentation rather than the content or details.

Perspective

The goal of the documentation should be to answer the questions of those who use it, as quickly and sensibly as possible. Toward that end, the documentation should be approached from the perspective of those who will be using it, not those who write either it or Puppet. The best reading on this subject is Kathy Sierra's Creating Passionate Users blog (unfortunately, it's now defunct, but there are great archived posts there). One of Kathy's main points about documentation is that it should provide the reader with new avenues of accomplishment, rather than just information on how to do every little piece.

So, as you write or organize documentation for Puppet, please ask yourself: Are you helping the reader find new ways to solve problems, or are you just describing the product for those who already know what they want to do?

Choose Your Own Adventure

The best way I could come up with for thinking about documentation from the perspectives of its different users was to follow the model of the old-school "Choose Your Own Adventure" books, where you get asked some questions and the plot unfolds based on your answer. The reason I think this is an appropriate model is that the different plot points were often the same regardless of your path, but the path you took still determined the plot itself.

For instance, nearly every documentation user is going to need to read the reference documentation at some point, so you can't just pick one user story in which to talk about the reference, but each user is going to want to read the reference for different reasons -- novice users will need it to know what resource types are available, while experienced users will need to look in the reference for details on resource types they already know well.

Given this idea, we should be creating index pages that answer questions on a given topic and then build paths between those index pages. There shouldn't need to be all that many index pages (maybe we should call these "hub" pages, or "intersections"?), so it's just a question of finding the main topics on the site, creating a hub for each one, then making sure they connect in sufficient ways.

Indexes

We'll also need something that's more like a table of contents page that basically lists all of the available documentation. This should be considered a last resort, because it means someone couldn't find a good path to where they wanted to go.