I often get stuck changing from reference to explanation in the middle of wirintg, so this is a great guide. Having a small How-To example in every reference entry for a API endpoint might be good, but you need to keep them seperate and concise, do not start with explanations.
Here is a extract from Ubuntus page about this:
> Writing security reference documentation, you will know that you should be producing clear and simple statements of fact. Explanation of a security feature or function, or showing how to use it – those don’t belong here. There is a place for them: a different place. If those things are required, then there should also be a security explanation topic, or a security how-to guide. This immediately makes life easier for the documentation author, who recognises that explaining and showing how-to are also important.
Examples in reference material are an excellent idea, and not at all in contradiction to the principles of Diátaxis. An example illustrates - like an illustration in any other reference guide - and provides something concrete to help grasp what's being described.
That's different from a how-to, talking someone through a problem.
Golang API pages collect all examples into a list at the top. Maybe do the same kind of things for stuff like "Quick explanations" and "Warnings/Gotchas". But it would get very subjective and potentially very messy and unmaintainable.
Here is a extract from Ubuntus page about this:
> Writing security reference documentation, you will know that you should be producing clear and simple statements of fact. Explanation of a security feature or function, or showing how to use it – those don’t belong here. There is a place for them: a different place. If those things are required, then there should also be a security explanation topic, or a security how-to guide. This immediately makes life easier for the documentation author, who recognises that explaining and showing how-to are also important.
https://ubuntu.com/blog/diataxis-a-new-foundation-for-canoni...