[WillAdams]

OIC.

I guess that the books at:

https://www.goodreads.com/review/list/21394355-william-adams...

which include a typesetting system, a font design language, a 3D renderer, and an MP3 implementation qualify as "small scripts"? What is the threshold for such? TeX.web outputs some 20,619 lines of Pascal code for conversion to C and compiling.

[ReleaseCandidat]

"Doesn't work" does not mean that you can't write such books/programs/documentation. It means nobody (yes, yes, exceptions ...) can maintain such code. Look at Jupyter Notebooks - the most used literate programming environment nowadays - and their usual content. The main problem of documentation isn't solved by literate programming: how can you make sure that any relevant documentation has been updated, so that the docs are still in sync with the code.

[WillAdams]

I find that having the documentation in the same file and interactive with, and having the ability to include formulae and diagrams helps immeasurably in ensuring that the documentation is updated as the code changes.

[ReleaseCandidat]

This sounds logical, yet I have never seen that in my own code, the code of colleagues at work or other code. If the documentation is not somehow automatically tested against changes in the code, the documentation in the same file is almost always worse (as in "more wrong") than adding the changes in another document. I don't know why it's easier to remember or for others to check for updates in "special" files.