[DanieleProcida]

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.

[euroderf]

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.