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.
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.
A explanation document could be structured into the following elements.
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.
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.
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.
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.
Since the explanation guide will not cover everything in detail, additional resources, books, context pages or scientific papers might be referenced and listed.
Explanation documents are normally not marked as specific “Explanation document”, but might look like a normal documentation page in the documentation system.
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.
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.
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.