- Keep diagram source (eg Graphviz dot) with the document.
- Write software developer manuals that can reference code robustly as the code changes (eg include code snippets from source based on regex).
- Literate Coding / Reproducible Research pattern. Eg, org file explains and generates/builds/runs code and graphs/figures which then get included back into the document.
Some of the problems
- At some scale, one needs a DAG (eg make) or to make every command idempotent with fast no-op. Otherwise, each little change to a source block takes too long and there is a worry that something didn't update which should.
- At some scale, the document becomes the size of a library/package and it does not compose and/or I want to run the code outside of the document.
- The unenlightened around me do not use Emacs so an org file is a "me" file. In some ways this is a plus as it keeps others fingers out of my pie but it also means no way to share the baking.
That was in the days before LLMs. As ellieh's #3 points out, things are different now (we all know that). I now have an LLM externalize org-babel. The LLM maintains an org or LaTeX document describing bits of work, an external library/CLI which runs to produce content including putting numerical results into LaTeX macros, a Makefile or Snakemake to regenerate content and figures. When things are found to change prior understanding the LLM remakes a section of prose in the LaTeX document. I then write my own notes or another LaTeX document so that the trip through eyeballs to fingers on the keyboard assures I keep some level of understanding.
Likewise, in the software documentation goal, it's far better to give a good LLM access to the source and have it generate documentation targeting some learning goal with follow exploration via Q&A than it is to read some prepared document that assumes my goal. Software documentation is kind of a relic useful only for those people that have not yet taken up LLM tools.