I am writing a lot of software and I feel that writing good documentation is very difficult. Since I am not aware of any structured theory about software documentation I started to organise my knowledge in this field and hope that doing this will help me to break down information in sensible units and organise documentation efficiently.
First, I would like to make a complete list of relevant concepts, that I will investigate in other questions.
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?
I identified the following concepts:
Information categories like recipes (“how do I…?”), references (like UNIX man pages) or expert knowledge.
User role like normal user, power user, system administrator and any other roles that the system defines like security officer, data officer, etc.
Medium like a hardcopy manual, contextual help, editable wiki.
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.