Revision 2.0
The most popular job of documentation for software is to explain to end users about how to use the features. However, producing high quality documentation is a challenging task even for people who have a great talent for writing. Beautiful text with colourful comparisons and apt synonyms – something that you will enjoy while reading fine literature – has a good chance of being more confusing than helpful.
Before starting to write documentation – regardless if it is a big project for describing a complex software product, a section showing how to use a small feature, or even a short message displayed at runtime – the author requires answers to three essential questions:
What not to explain?
What to explain?
How to let readers get the most out of explanations?
It may seem that the what not to explain? question may not come first and the primary author's focus should be on the new information. Yet, the very first step for constructing documentation is to understand what readers already know. To be able to obtain this knowledge, the author should be aware of how the concept of target audience applies to documentation.
The what to explain? question is also tricky. The information that requires explanation is not a static dictionary where all terminology is arranged alphabetically. The scope of the new knowledge is tightly coupled with the tasks that the user may be performing by interacting with the software product. The job of documentation is to make sure that the essential terminology and operations are presented in the way that the user understands how to use the software product right in that context.
The arrangement of contexts in the documentation is crucial when the author should decide about how to make the documentation available to users. Users will get the most out of the documentation if they get only the relevant information. In practice, it requires that the author seek to predict what problems demand most attention.
What not to Explain: Scope of Target Audience
As a means of explanation, documentation is only valuable when it provides new knowledge. New facts must be linked with what readers already know.
To serve best its purpose, documentation must differenciate users based on their familiarity with the software product, with similar products; it should also take into account users' general level of expertise in the domain where the software product functions.
Documentation for beginners differs from documentation for advanced users. Documentation for developers differs from documentation for end users. Thus, two readers who belong to the same group have a similar understanding of the software product being documented while two readers who belong to different groups will not benefit from documentation if it only targets one of these groups.
Designating documentation for specific groups aims to assist in arranging explanations. Readers who have installed the software product for the first time should associate themselves with the beginner group. Readers who have experience in constructing programs should be able to read comfortably materials that contain a lot of technical information.
Based on these generalized assumptions, it is not easy to develop a clear and unambiguous system of criteria. For example, documenting a newly developed text editor, the beginners group might include all people who have not used this editor before. This group will also include people who have used another text editor. Documentation is of different value for each of the segments of the beginners group. Explanations present a great value to absolute beginners and have a good chance to be totally skippable by users of other editors.
A more effective approach is to define the target audience based on documentation own features. Documentation describes relations of concepts (or terms) in the context of the software product. When the relations among all terms are defined, the documentation is complete. It works the same for small sections, too. As soon as all terms relevant to the topic are defined, there is nothing more to explain.
To introduce terms specific to the product being documented, documentation must rely on concepts that readers already know. For example, here is one of the definitions of the term documentation in the Merriam-Webster dictionary:
: the usually printed instructions, comments, and information for using a particular piece or system of computer software or hardware
For this definition to work, readers are assumed to be familiar with the terms instruction, comment, information, system of computer software, and system of computer hardware. Since these terms must be known, the dictionary does not explain in this context what they stand for. If this definition were to be treated as documentation, then the term documentation would belong to the scope of the product and the terms instruction, comment, information, system of computer software, and system of computer hardware would reside in the scope of the target audience.
In documentation, the concept of target audience is not about people. It is about which terms may stay unexplained. Users are trusted to be knowledgeable of the domain where the software product is applied.
What to Explain: As a Story
No good explanation appears in the form of a list of definitions. Although it would be easy to construct such a list, users would not benefit - except for some extraordinary cases - from this information even if the evaluation of the target audience (all terms that need not be explained) were precise.
The secret of making documentation useful is in presenting product related terminology gradually so that it is always linked to what readers already know. As the reader progresses through the documentation, each acquired piece of information contributes to the expansion of their knowledge. In other words, when the reader consumes information from the documentation, the list of terms that need not be explained grows.
Referring back to the example that demonstrates the definition of the term documentation in the dictionary, dictionary becomes part of the scope of the target audience as soon as the reader fully understands that definition.
Presenting new facts about the product in documentation is similar to telling a story. Each character, event, and description is linked to what has been told so far. Any perceived gaps account for confusion and inconsistencies. Documentation is only different in the material it uses. In place of characters, events, and descriptions it makes use of terms: unambiguous interconnected concepts.
Documentation is not as fascinating, intriguing, mysterious, or emotional as fine
literature. Nevertheless, explanations are expected to be well written stories. The principal advantage of documentation is that it always deals with something tangible and relevant. While its story unfolds, users are becoming more capable of using the product.
The documentation author sees the software product as a system of related terms. Each term is introduced in relation to problems that the product is supposed to solve. Yet, there is a clear distinction between readers' perspective on a problem and the documentation author's. For a reader, a problem is a task and the software is a tool. Readers refer to documentation to be able to effectively use the product.
From the author's perspective, a problem is a context that includes a certain number of new terms and the terms from the scope of the target audience.
Get the Most Of: Context
From the user's perspective, a problem is a task from real life that they intend to solve by using the product as a tool. Users form expectations about what the product should be capable of. When addressing documentation, they seek information about how these expected capabilities are realized. This assessment goes on constantly: not only before but also while the user interacts with the product.
At runtime, users are guided via the interface from one context to another. These interactions follow predefined patterns and align with the problems that the product is designed to solve. At each step, the user makes choices, inputs information, activates functions.
When documenting users' interactions with the product, the author sees a substantially bigger picture which is composed of distinct layers:
It is important to be aware of what users must know in order to interact with the product at the given stage: the scope of the target audience.
All terminology used in each context is linked with relevant terms from the scope of the target audience.
The documentation explains how data, provided and captured, is retrieved or saved by background processes.
The documentation is the only place where the implementation details can be revealed to the end user along with reasons, rules, limitations, and even promises.
The interface of modern software products is purely instrumental. It enables users to supply data to the running application and retrieve relevant information. It is unable to provide all the guidance that users may require.
Providing additional information via documentation is a reasonable approach since documentation does not have the functional restrictions of user interface. Ironically, the ability to provide detailed instructions is also a weakness of documentation. The author may give all information that users require. But it is extremely easy to overwhelm and to confuse. Documentation must apply restrictions to what users may learn. It is the current context that prescribes the amount of information to be provided as a relevant explanation.
The smallest and most specific context where the user interacts with a software product is a single piece of information, such the name of a single interface element. The largest context is when the user does not even have the product installed.
Comments