Discussion on improving documentation

[$bill]

Quoting Jacob Kaplan-Moss on what to write (Writing Great Documentation series http://jacobian.org/writing/great-documentation/ 11-2009)

"Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation.

At a high level, you can break down the different types of documentation you need to provide into three different formats:

* step-by-step tutorials,
* overviews and topical guides to the various conceptual areas of your project, and
* low-level, deep-dive reference material."

To their credit, Kinook's documentation covers all of these areas. The strong area is their low-level reference material which is especially through and current with each release.

I would advocate ADDING to the documents available rather than replacing or rewriting what we have. I would place the emphasis on NEW "overviews and topic guides" written in a different styles and/or delivered in a different format. New uses really need to 'get' the concepts of UR to use it effectively.