How to categorise information in end-user documentation?

Question

One of the greatest piece of documentation I ever read is the TeXbook by Donald Knuth—the manual of the TeX typesetting system, and I used it in my first analysis.

As far as I can tell, the type of information conveyed by documentation falls in three categories: recipe, reference and expert knowledge that I describe hereafter.

Which categories am I missing?

Recipe

A recipe answers a question like “how do I solve that problem with this software?” and binds the problem world with software features. Chapters 3, 7 and 8 in the TeXbook answer questions like “How do I run TeX?” or “How do I type text?” and provide the user with recipes. Other software packages often contain installation or backup procedures that fall in this category.

Reference

A reference documents all the needed details on some piece of software. It is useful for the user knowing that “this feature is useful to solve that problem” and wanting to know if it can parametrise “this feature” to solve a close problem. It is also useful for troubleshooting the software when it gives unexpected results. Chapter 14 “How TeX Breaks Paragraphs into Lines” in the TeXbook is an example of a reference text. UNIX manual pages almost always belong to this category.

Expert knowledge

Expert knowledge pertaining to the problem solved by the software also belong to the software documentation. Reasons for this are at least:

1. Users are not experts in the area where the software is useful.

2. Experts use varying terminology and methodologies to describe or solve problems.

For 1. mathematicians reading the TeXbook also learn the basics of design and layout: they get aware that there is a structured knowledge in this area and learn the names of the basic concepts involved, so that they can phrase out problems and get help. For 2. it is useful to “fix the notation” in the software documentation and this is best done by providing some high-level or background information.

Hence expert knowledge contained in the user documentation binds the conceptual organisation of the problem as it is known to the software designers to the conceptual organisation of the problem as it is known to the software users.

Answer 1

I think you've done a very good job summarizing most types of documentation into those three categories. I would like to add two more:

Beginner Knowledge/Bootstrapping

You could classify this under Recipes, but I think it's different enough to deserve its own category. A recipe already assumes a basic knowledge of the system. Writing a recipe for food already assumes a basic knowledge of the cooking domain: You should already know what a tsp is (if you're using that strange system of measurements. :) ), how to use an oven, microwave, etc.

For someone who has never cooked or made food in their life, you'd want a gentle introduction to the entire system, showing them what they can do, and giving them little tidbits of coolness along the way to keep them interested.

The same applies to documentation. A beginner will quickly throw away a recipe book, because they don't have enough domain knowledge to even appreciate the recipes. Therefore, they need some beginner knowledge, or bootstrapping. Here's some points about this documentation format:

• Very basic, making sure to explain every possible unfamiliar term. This can be frustrating to some users, but is essential in order to educate anyone looking at the documetentation
• Lots of small examples to keep the user interested. These aren't recipes, per se, but they are little things to keep the beginner interested, knowing that this product does cool stuff
• Lots of links to other places in the documentation (Recipes, Expert Knowledge, etc.) where they can learn more about some of the concepts being discussed
• Short enough to be easily digested. No one wants to read a 300-page introductory novel

Marketing

You could argue that this isn't really "documentation", but it often gets included in documentation. These are descriptions of "why our product is so awesome that you should use it". It's a long-winded description of how the product beats the competition. This is less prevalent in open-source software, but you see it all the time in commercial software.

Answer 2

Some of this varies if you are documenting software or hardware, but possibilities:

1. Tutorial (not quite similar to what you call Recipe, depends on the situation). But at least a brief "Hello World" type of thing, and perhaps more. Some people learn best from examples. Others just turn right to the reference
2. Installation / turning the darn thing on
3. Uninstallation / turning the darn thing off
4. Interacting with other "standards". How does this gizmo work with Spring, XML, USB, Roku, LTE, CloudServices, etc. Is there an Eclipse plugin?
5. Dangers / Warnings / Requirements / Gotchas. Don't use underwater, it works but certain options are disabled in Windows RT, requires Java 6 or higher, it doesn't work with IE6, we haven't tested it on Android 2.2 and earlier, etc.
6. FAQ, plus a link to any on-line help
7. Legal Notices (if required, hopefully you can avoid these) Parts are licensed from the FooBar Corporation, parts are GNU, Not for use in Diagnostics, etc...
8. Glossary (I stole this from @Marco's comment)

Answer 3

I think that Tutorial as a category is worthy of distinction from the categories listed. A tutorial is not a recipe as you have described it because it is not necessarily a "how". It could be a combination of "how", "why" and "what" used to facilitate understanding of other items. A recipe is just "how" and stands alone whereas a tutorial is teaching an element that may be entirely abstract and only of any use in combination with other items. In fact one might even consider a Recipe as a subcategory of Tutorial.

Answer 4

I think you should add an "Indexing" category. That describes the mechanism to pull all of the other information together via tags and hyperlinks so that it can be accessed in a context-sensitive manner from the application and from an index within the application. If the information isn't easily found the users are going to go to Google and skip the documentation.