What documentation do users actually need ?
Have a look at this from wikipedia:
Unlike code documents, user documents simply describe how a program is used.
In the case of a software library, the code documents and user documents could in some cases be effectively equivalent and worth conjoining, but for a general application this is not often true.
Typically, the user documentation describes each feature of the program, and assists the user in realizing these features. A good user document can also go so far as to provide thorough troubleshooting assistance. It is very important for user documents to not be confusing, and for them to be up to date. User documents need not be organized in any particular way, but it is very important for them to have a thorough index. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do. API Writers are very well accomplished towards writing good user documents as they would be well aware of the software architecture and programming techniques used. See also technical writing.
User documentation can be produced in a variety of online and print formats However, there are three broad ways in which user documentation can be organized.
- Tutorial: A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks
- Thematic: A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user. Some authors prefer to convey their ideas through a knowledge based article to facilitating the user needs. This approach is usually practiced by a dynamic industry, such as Information technology, where the user population is largely correlated with the troubleshooting demands
- List or Reference: The final type of organizing principle is one in which commands or tasks are simply listed alphabetically or logically grouped, often via cross-referenced indexes. This latter approach is of greater use to advanced users who know exactly what sort of information they are looking for.
A common complaint among users regarding software documentation is that only one of these three approaches was taken to the near-exclusion of the other two. It is common to limit provided software documentation for personal computers to online help that give only reference information on commands or menu items. The job of tutoring new users or helping more experienced users get the most out of a program is left to private publishers, who are often given significant assistance by the software developer.
Alright, where to start…
We’re about 10 years out of date. No one read tons anymore. Talking about chapters and documents means the documentation is disconnected.
“The job of tutoring new users or helping more experienced users get the most out of a program is left to private publishers, who are often given significant assistance by the software developer.” This may have been the case and even today, in some companies, they want their training to be paid for. But is this the right approach?
We need to rebind all these forms into a new delivery strategy that provokes user satisfaction.
The users needs guidance
Guidance, not help. If your user needs help, then you’ve lost him. You need to know what users you are catering for: beginner, experienced, expert. This will depend on several factors, some of which are:
- is the software new (and if so it it easy?)
- are you changing practices?
- are you bending the rules (doing a process in an unexpected way for instance)?
- do users have to wait for training?
Deciding what guidance to give is part of designing an editorial strategy. When it’s done stick to it. Parts of the information provided can say ‘expert use’.
How do you know what the user needs?
You should. Even if you are starting out, you have an idea of who you aiming for, don’t you? Then as you go, feedback and support issues will reflect needs.
What do i do first?
Cover basic needs only. See whats advised in agile methods:
The following practices will help you to simplify the documentation that you write:
- Keep documentation just simple enough, but not too simple
- Write the fewest documents with least overlap
- Put the information in the most appropriate place
- Display information publicly
Yes this applies to agile documentation. Documents are referred to – we refer to topics.
The following practices will help you to determine what to document:
- Document with a purpose
- Focus on the needs of the actual customers(s) of the document
- The customer determines sufficiency