I find that I mostly use diagrams for "explanation documentation". This is by far the best description: https://documentation.divio.com/explanation/ https://doc

I find that I mostly use diagrams for "explanation documentation". This is by far the best description: https://documentation.divio.com/explanation/ https://documentation.divio.com/explanation/ > 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. Where UML goes wrong is that it tries to be a very detailed technical description. Usually, you just want a reference guide for that sort of thing. And reference docs are rarely maintained manually, at least not with any accuracy. I've yet to find a good system that can generate diagrams for technical reference that's usable. It's hard to say what fits and what does not in a diagram, because it depends on the point you're trying to make. But I usually find that "explanations" are really tricky to get right. UML's a handy place to start thinking, but you're almost always going to cut out a lot of detail to make an explanation easy to understand.