Documentation is a tool for creating shared understanding. If you don’t need to share your understanding, don’t write docs.

Note however that sharing understanding works on the people axis and on the time axis. Docs allow you to share your current understanding with your future self. They’d better be general enough to be true then, though.

Nowadays I find Gemini pro to be able to accurately document a complex workflow within minutes just by looking at the sources and sometimes even just logs, so value of low level docs is questionable. High level requirements - essentially how it’s supposed to work and what for - is very valuable, as it allows you and the model to cross check whether things work as they were intended.

I write and read lots of documentation. Diagrams are not a common feature of that.

I'd rather have a single concept diagram than a thousand words of docs. To each their own I guess.

None other than ticking boxes and shutting up the people that keep asking for such things to be produced. Who then invariably don't have the attention span to do anything with the diagram. That's literally the only reason I have for creating them. Otherwise it's a tedious activity that gets in the way of developing, slows me down, and just interrupts my creative process. I usually have better things to do.

And as you might understand from what I just said, I rarely produce any diagrams. I've been active as a developer since before UML got popular and then peaked and then faded into obscurity. I still have a signed (by Martin Fowler) copy of UML distilled on a shelf somewhere gathering dust. First edition and everything. I don't think it's very valuable. Waste paper basically. But contact me if you feel otherwise. It's in pristine condition because I never did much more than thumb though it and shelve it.

25 years ago, any self respecting architect had expensive licenses for things like rational rose or visio. And they'd be fiddling with those tools for hours to produce detailed class and other diagrams. And those diagrams were as useless then as they are now. Epic waste of time. People stopped buying and using those tools. This was once a very big industry that has now imploded to next to nothing. Nobody is buying, very few people waste budget on this crap. It's a niche market with some niche revenue. Tens of millions of developers ignore these tools.

What do plantuml, mermaid, and other OSS diagramming tools have in common? The people that make them don't eat their own dogfood to document how their own software works. You can have some fun looking for diagrams in OSS projects. With few exceptions, this is not a thing (devops people seem to have a weird obsession with diagramming. And overengineering). I'm not aware of many serious OSS project where developers have bothered to document even a tiny fraction of their software with diagrams. Including all the major OSS UML diagramming tools.

The documentation for these contains plenty of examples of course (typically very simplistic). Just not any that document how the tool is designed or works. I'm not judging. I wouldn't bother either for reasons that I articulated above. But I find it ironic that even diagram tool developers don't seem to feel an urge to use diagrams for their own stuff. Makes you wonder why they bother creating the tool? You'd have to be passionate about diagramming tools but not so that you'd want to use them for your own software.

The answer is literally in the same sentence you quoted…