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.

https://ubuntu.com/blog/diataxis-a-new-foundation-for-canoni...