The following passage is quoted from: https://diataxis.fr/explanation/#writing-good-explanation
When writing explanation you are helping to weave a web of understanding for your readers. Make connections to
other things, even to things outside the immediate topic, if that helps.
Provide background and context in your explanation: explain why things are so - design decisions, historical
reasons, technical constraints - draw implications, mention specific examples.
Explanation guides are about a topic in the sense that they are around it. Even the names of your explanation
guides should reflect this; you should be able to place an implicit (or even explicit) about in front of each
title. For example: About user authentication, or About database connection policies.
Explanation can consider alternatives, counter-examples or multiple different approaches to the same question.
You're not giving instruction or describing facts - you're opening up the topic for consideration. It helps to think of
explanation as discussion: discussions can even consider and weigh up contrary opinions.
One risk of explanation is that other things can tend to creep in. Explanation should do things that the other parts of the documentation do not. It’s not the place of an explanation to instruct the user in how to do something. Nor should it provide technical description. These functions of documentation are already taken care of in other sections.
The reason for x is because historically, y...
Explain.
W is better than z, because...
Offer judgements and even opinions where appropriate..
An x in system y is analogous to a w in system z. However...
Provide context that helps the reader.
Some users prefer w (because z). This can be a good approach, but...
Weigh up alternatives.
An x interacts with a y as follows:...
Unfold the machinery's internal secrets, to help understand why something does what it does.