[baq]

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.

[jillesvangurp]

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

[baq]

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