Personally, I tend to use simple diagrams to illustrate the basics. I try to keep them as small and minimal as possible. This way I can reduce the risk of exces

Personally, I tend to use simple diagrams to illustrate the basics. I try to keep them as small and minimal as possible. This way I can reduce the risk of excess work if something changes. If the case, that I want to illustrate, is too complex to fit into a small ASCII diagram, it most likely should be better modeled in a dedicated modeling tool (I use Sparx EA). Also I think that modeling languages like Mermaid are a nice alternative for small to medium diagrams. But these wont work in code comments. But they can be fitted into a Markdown file.