How to introduce Explanation Content into Documentation

The best way to approach this topic is to start by talking about the significance of the explanation quadrant: why do we need the explanation quadrant?

If you are not familiar with what the explanation quadrant is then you want to check out the diataxis framework. The diataxis framework divides documentation into four quadrants: tutorials, how-tos, reference guides, and explanations.

We have covered each of them in this blog. For more perspective on them, you should check out our content on each of them in addition to reading the diataxis framework itself.

The first three are very common, as they are standard documentation sections in most documentation. They have been highly developed over the years and are now part of conventional documentation standards.

However, it is hard to see dedicated explanation sections in most documentation. Rather, what we would usually have is bits of explanation content stashed into sections dedicated to the other three types of documentation.

The diataxis framework established a new documentation standard, and it has been gaining an increasing amount of adoption across most software technologies— think of popular open-source projects like Django and GitLab both of which have adopted the framework.

The framework popularized the need for the fourth quadrant: the need to have a dedicated documentation section for just Explanation Content, instead of the current practice where Explanation Content is squashed into the other types of documentation, mostly as snippets.

In fact, Explanation snippets in other documentation have only acted to decrease the quality of the other forms of documentation, derailing them from their intended purpose, and adding unnecessary content that annoys users.

By having a dedicated section for Explanation, we can keep each type of documentation aligned with its purpose, which would help increase the overall usability and quality of documentation.

What is Explanation?

The diataxis framework defines explanation as a discussion that clarifies and illuminates a particular topic. An explanation is understanding-oriented.

MUST READ: Types of Technical Writing: How to Choose? (2023)

The role of Explanation Content is to broaden, deepen and clarify a reader’s understanding of a topic. Explanation Content is the only type of documentation that doesn’t necessarily need to be about a product.

You can think of Explanation Content as theoretical knowledge that doesn’t necessarily have to reflect in actual practice, but that enables you to gain perspective on a topic, modify the way you think about the topic, and perhaps, increase your appreciation of the richness of the topic or subject.

As an example, let’s consider a scenario where you are a beginner to Blockchain technology. If you are very practical in nature, you might as well just ignore understanding the details of Blockchain technology, and focus more on mastering one of the practical aspects of blockchain technology. Perhaps, you picked Cryptocurrency.

While your knowledge of Blockchain technology might be rather shady, you might be a guru in the cryptocurrency market. But assume instead, you thirst to know more about Blockchain technology. This is where explanation content comes in to help you explore the origins and internal mechanics of the technology and how it works.

Think about the sensation you gain on discovering these insights: do you notice the more perspective you gain? The deeper and broader knowledge of the possible applications of the technology? The feeling of more confidence you gain?

The often given reason for the un-need of explanation content is the fact that it isn’t practical, and hence, not relevant.

For instance, in the illustration above, you could be making a fortune in the cryptocurrency market without knowing a bit about blockchain technology!

However, the issue is that this argument often misses a very important point: explanation content helps you gain perspective and deep insights on a subject, and with that comes a more active form of knowledge, intuition, and creativity, and an ability to predict the future trends of a subject, event or technology.

MUST READ: Top 4 Core Duties of A Technical Writer

With your richer understanding of blockchain technology, you can better reason out other possible applications of the technology: think of innovations like Web3.

You probably won’t have been able to predict the rise of Web3 if you’ve only focused on the Cryptocurrency market without really understanding its roots.

This active form of knowledge will also help you intuit future trends and better prepare for them.

Rules for Creating Good Explanation content

Below are the rules for creating good explanation content on your documentation.

Provide context

Since explanation content is understanding-oriented, to help your readers understand a topic, then you must provide enough background information and context on the topic.

No subject or topic stands in isolation. It is part of a web of other topics or subjects. Talking about other topics or subjects it is related to will help readers understand the topic in relation to other topics.

You want to talk about the bigger picture, history, and origins, providing detailed reasons and justifications on the subject.

For instance, to help readers understand Web3, then you must provide information about Web2 to provide a good context to help them better understand the motivation, and the reason for the rise of Web3.

Discuss alternatives and opinions

Providing your reader with opinions that have been expressed on a subject will help them understand the topic even better as it helps them see the subject from different angles and perspectives.

The same goes for alternatives. It empowers readers with deeper insights into the subject.

Don’t give instructions

Giving instructions in Explanation Content would derail the content from its main purpose. Instructions must be left to the practical aspects of documentation like tutorials and how-to guides.

You must keep your explanation content focused on just helping a reader gain a richer understanding of a topic.

Common Implementation of Explanation Content

If the whole idea of having a separate section for explanation content is still new to you, then you might be rather unsure of how to implement it in your documentation. So in this section, we would go over some common implementations of the explanation content.

MUST READ: How to create a freelance technical writing portfolio from scratch

It should be noted that the explanation content could be called a variety of names in your documentation. You could have it implemented as a conceptual guide or topic guide.

Software-specific terminologies

Perhaps your software product comes loaded with a lot of new technical terms that could pose a problem to users of your product? Explanation content is a good way to handle this problem.

With an explanation section in your documentation, you could have dedicated pages for your software-specific terminologies, providing your users with enough context and background to help them better understand these terms—as Lootlocker does in the image below. Notice the explanation section is called Background.

The explanation section is a good place to provide explanations on how your software product implements these inclusive practices, and how you intend to improve in the future to ensure continued support for these inclusive practices.

Summary

So that’s it for this article. If you need to make more clarifications on the topic, please drop comments. We are glad to help you introduce explanation content into your documentation.