The Grand Unified Theory of Documentation
In this article I want to talk about one interesting theory of developing documentation for systems and programs. Its authors claim to have created nothing less than “The Grand Unified Theory of Documentation.” The theory sets out ideas and rules that are often found in various documentation development methods and are applied in practice.
The main value of this theory is not that it reveals hidden secret knowledge, but in the careful systematization of this knowledge and in useful tips for developing each type of document. I won’t say that I 100% agree with all the rules outlined in the theory, but there are a lot of useful and rational thoughts in it.
Ancient philosophers believed that everything in the world consists of four primary elements: earth, water, air and fire. These elements interact with each other and give rise to all the objects around us.
The authors of the “Great Unified Theory of Documentation” propose to identify four main elements in the documentation of programs and systems. These elements describe the same object in different ways and generate knowledge and understanding in the reader and user.
The unified theory of documentation is described in detail on the website https://documentation.divio.com. The secret to good documentation is that there is no single entity called “documentation.” In fact, it consists of documents of different types. Each has its own tasks, its own format, its own audience.
Four types of documents
So, there is no single and indivisible documentation. According to the theory, it consists of four types of documents:
Tutorials – textbook.
How-to guides – guide.
Reference – reference book.
Explanation – explanation.
Each type solves its own special problem and requires a special approach to its development. Users may need each document type at different times and under different circumstances. The documentation must contain documents of all four types. It is important that they are clearly distinguished and not mixed with each other.
1. Tutorial
Helps the reader learn the system.
Allows a beginner to start working with the system.
Basic form: lesson.
Analogy: teaching a small child the basics of culinary art.
A textbook is a document that helps turn a student reader into a user of the system. Textbook documents are usually the most voluminous in the documentation package. At the same time, writing them is not easy, because they must be easy to understand, meaningful, and at the same time carefully verified and reliable.
Recommendations:
Let the user learn by doing. The textbook should be exercise-oriented. Exercises should cover a wide range of tools and operations, from simple to complex.
Help the user get started. Start by describing the simplest practices for using the system. The actions of a beginner may differ from the actions of an experienced user. A primer is not a description of best practices for working with the system.
Make sure the lessons work. One of the goals of a textbook is to instill confidence in the beginner: in the software, in the textbook, in the author, and, of course, in his own ability to achieve his goals. This is facilitated by a friendly tone, clear language, and a logical structure of presentation of the material. But the most important thing is that everything described in the document should work. And work exactly as stated in the text. If the actions described in the textbook lead to an error or unexpected results, then the training has failed.
Provide visual results of all user actions. All student actions should lead to understandable results, even if they are insignificant. Don't force the reader to do a lot of strange and incomprehensible actions before he gets some visible result. The effect of each action must be visual, obvious and fast enough. The connection between the result and the actions taken should be obvious.
Ensure that all lessons are repeatable. All results described in the manual must be reliably reproducible. Achieving this is not easy: readers may use different operating systems and tools, and they may have different levels of background knowledge and experience. The system itself may change over time. The tutorial should work for everyone, all the time.
Don't get carried away with abstract concepts. Focus on concrete steps rather than abstract concepts. You will be very tempted to introduce abstractions into the text, but any learning goes from the particular and concrete to the general and abstract. There is no need to force the student to operate with abstract entities before he learns to perform concrete actions.
Provide the minimum necessary explanation. Do not explain anything that the student does not need to know to complete the lesson. Other types of documents are intended for extended explanations. During the learning process, detailed explanations will only be distracting. Provide the reader with the minimum necessary explanation and provide a link to an extended description of the processes.
Focus only on the steps the user needs to take. The content of the textbook should be focused on the task at hand. Don't be distracted by other options for performing actions or optional customization options for the application. None of this matters: your student doesn't need to know this right now to be successful.
2. Guide
Task oriented.
Shows users how to solve a specific problem.
Basic form: step-by-step descriptions of actions.
Analogy: a recipe in a cookbook.
The manual walks the reader through the steps required to solve a real-life job problem. It differs from a textbook in that it is aimed at readers with basic experience with the system. The manual provides an answer to a question that only a user with some experience can formulate.
Recommendations:
Describe specific steps leading to the goal. A how-to guide should contain a list of steps that the user must follow to complete the task. In this type of document, you can omit the description of basic actions, for example, opening a file. In a manual, it is not necessary to achieve unconditional repeatability of results, as in a textbook.
Focus on results. Leadership must be aimed at achieving a practical goal. As in textbooks, detailed explanations are inappropriate here.
Describe a way to solve a specific problem. Management must answer the question “How can I…?” The reader of the manual knows what he wants to achieve, but does not yet know how.
Provide descriptions of different ways of working. Include in the manual descriptions of different ways to do the same thing. Provide the user with information on how he can adapt the described algorithm of operation to different system configurations and to different variations of the original problem.
Don't strive to be fat at any cost. The convenience of the manual is more important than its completeness. The manual does not necessarily contain complete and exhaustive theoretical and practical information about the subject of the description. A bloated manual will not only not help the user, but will also make it difficult to find the right solution.
Use a description of the user's question in the section titles. The title of a how-to section or document should tell the user exactly what question it addresses. “How to Create a Class-Based View” is a good title. “Creating a Class-Based View” and “Class-Based Views” are bad titles for a section of a Tutorial type document.
3. Directory
Focused on obtaining reference information.
Describes the mechanism of operation of the system and its parts.
Basic form: technical description.
Analogy: reference article in the encyclopedia.
Directories have only one function – descriptive. Ultimately, the reference book boils down to a description of the system code, interface parameters or file format. The reference may contain examples illustrating the use of the system, but should not contain an explanation of basic concepts or a description of how to solve user problems. The manual contains technical information but does not contain instructions. In many cases, it is convenient to generate directories automatically – based on the source code of the system. The directory can hardly be called interesting reading; its purpose is to make searching and obtaining technical information as fast and efficient as possible.
Recommendations:
Rely on the system source code. Use the same structure in reference documentation as in the source code or architecture of the system or part of it. This will help the user to see an unambiguous connection between system objects and document sections. This will help the document author quickly identify sections that are missing or need updating.
Maintain strict consistency. Present information uniformly and in strict order, like in an encyclopedia or dictionary.
Do not add anything unnecessary to the directory. The only task of the reference book is to describe the system objects as unambiguously and completely as possible. Any other information – explanations, instructions – will not only distract the reader, but will also complicate the maintenance of the reference book. But if necessary, the reference book may contain illustrative examples.
Be as precise as possible. The contents of the directory must be accurate and constantly updated. Any discrepancy between the description object and the reference text will inevitably mislead the user.
4. Explanation
Focused on understanding.
Explains complex algorithms and processes.
Basic form: analytical explanation.
Analogy: an article about the history of cooking.
An explanation is intended to provide a detailed, in-depth description of a specific topic. This type of document allows you to expand the description of the system, consider the system from a higher level or even from different points of view. In the documentation for some systems, the explanation is not separated into a separate document, but is scattered throughout other documents in the form of notes or additional inserts. Explanations are much more difficult to create than other types of documents. It requires an analytical approach.
Recommendations:
Provide context. When explaining an issue, describe its background and the context in which it is found. Explain the logic behind the design decisions, outline the historical reasons, and list the technical limitations.
Give alternatives. An explanation may describe several alternative approaches to the same issue. You can also cite and analyze opposing opinions.
Do not add instructions or reference information. The explanation should not contain information that is contained in other parts of the documentation. Links to the relevant sections are sufficient.
Why is it important
Separating documents by type allows you to get clear answers to the questions:
for the author – how to write? what to write? where to write?
for the reader – where to read? when should I read it?
Quadrants with document types are constantly trying to merge:
the textbook and manual describe chains of practical steps;
the manual and reference book contain information needed in daily work;
reference book and explanation contain theoretical knowledge about the system;
The tutorial and explanation are useful for initial and in-depth learning of the system.
It is difficult to resist this natural attraction of document types to each other, but we must be firm and adamant.
The approach outlined in the theory can be used not only when developing documentation, but also, for example, when designing knowledge bases. After all, what is called “documents” in theory does not necessarily have to be a document in the classical sense. This can be any piece of information. For example, a page or section. The main thing is that this unit is assigned one (and only one!) of four labels such as “textbook”, “guide”, “reference book” or “explanation”. These are a kind of lighthouses in a huge sea of information – they will help not only our readers, but also ourselves. After all, these are clear, unambiguous guidelines for structuring and organizing information.
Plato wrote that before creating the cosmos, one must first isolate and order the four elements. Only after this can they be combined into a single harmonious whole.
