5 of 7
whitespace edit to prevent automatic deletion
Adam Lear
  • 31.3k
  • 8
  • 100
  • 125

Which concepts are pertinent to plan a “end-user documentation” strategy?

I am writing a lot of software and I feel that writing good documentation is very difficult. I started to organise my knowledge about software documentation and hope that doing this will help me to break down information in sensible units and organise documentation efficiently.

Which concepts are useful or relevant when describing user documentation? How does these concepts interact with each other. Is there any methodology I can use to analyse my software and devise a pertinent documentation strategy? Is there any structured theory about software documentation?

Basic example: Information categories

Let me give an example of a concept that I consider useful when I am writing documentation. 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.

Recipe

A recipe answers a question “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” 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 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.

Conclusion

Not only the contents is important but also its audience, which leads to categorise users according to their “roles” (e.g. system administrator, normal user, power user, data officer, and so on) and the “medium” which determines how the the information is presented.

These concepts interact one with the other and lead to a variety of questions: When is it useful to write a handbook for each role? What should go in hard copies and what in the on-line reference? When is it useful to run a wiki gathering “recipes”? With these examples, I hope I could provide a useful explanations of what I understand under “concept” and “interaction” in my questions (copied form above):

Which concepts are useful or relevant when describing user documentation? How does these concepts interact with each other. Is there any methodology I can use to analyse my software and devise a pertinent documentation strategy? Is there any structured theory about software documentation?