An explanation document describes a specific topic in detail. It contains background information, context and discussion of concepts. It is a theoretical document used during the education of the readership.
What is an explanation document?
According to Wikipedia, an explanation is a set of statements usually constructed to describe a set of facts which clarifies the causes, context, and consequences of those facts.
The purpose is to provide additional documentation, know how, guidelines and example to understand the background of a specific topic. Typical methods, use cases, processes, key words, practice are described to educate the user.
What are the elements of an explanation article?
A explanation document could be structured into the following elements.
1. Introduction
A short and brief intro to the topic. It should contain a definition as it might be written in the glossary of the product. If a reader or user only has limited amount of time or attention span, this should be enough to gain a very basic understanding of the topic.
2. Theoretical knowledge and background
Provide and list the theoretical and background information and concepts that are related to the explanation topic. Keep it brief and use the language of the reader. If there are specific scientific terms, they should be introduced. For deep-dive into specific topics, use links.
Use rich media as images, screenshots, videos or other helpful media files.
3. Specific topics
If there are specific topics or areas that are relevant, list them separate and introduce the concepts behind them. Also here – add images, pictures and other illustration elements.
4. Examples
If possible, add examples and describe them so that the user can see how the concept of the explanation document relates to the example. It should not be abstract or unrelated.
5. Further reading
Since the explanation guide will not cover everything in detail, additional resources, books, context pages or scientific papers might be referenced and listed.
What are great examples of an explanation guide?
Explanation documents are normally not marked as specific “Explanation document”, but might look like a normal documentation page in the documentation system.
Microsoft Teams – Voice routing: What are dial plans?
Starting with a short introduction to the topic “dial plans”, specific sub-topics as tenant dial plan scope” and “tenant dial plans” are described. It ends with a list of related topics and AI-generated recommended content.
URL: https://docs.microsoft.com/en-us/microsoftteams/what-are-dial-plans
Atlassian Document Format
Targeting developers that integrate with Atlassian products as e.g. the Jira Cloud platform, this page explains the Atlassian Document Format.
It is quite short and explains the technology being used (JSON schema and JSON structure). The concept of Nodes and different types of nodes (e.g. block node, …) is also described.
URL: https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
Want to write better explanation guides?
If you have a question or need some more information about explanation document, reach out to us. Subscribe to our newsletter to get more information and content about multilingual documentation.
This page is part of the comprehensive list of documentation types.
[Continue reading]