This is the name of a concept to combine source code and highly structured human-readable documentation, such that the main artefact is the documentation, and the secondary artefact the full source code extracted from it. Any change to the source means changing the explanatory documentation of the goals and reasoning at the same time. It was invented by no other than Don Knuth, and he, together with his collaborators, wrote the TeX program in it, to show how it is useful in practice.
I myself have used the technique in various occasions at work, for example when taking on an important but almost unreadable piece of code I inherited at work, to preparing sources for a complex algorithm for handover when I was leaving another larger project, and also in leisure coding.
The tool which is most widely used for this approach today is Emacs org-mode. It has the advantage that it works for every programming language, and you will likely find full examples for all languages you use, but many other tools (for example for vim) exist.
I’ve tried this a few times. I don’t think it works.
Basically the way you want to explain a piece of reasoning , and the order in which things need to be defined for a program, are different. You end up either making the document match the code structures, or the code structure match the document. Both are bad.
Literate programming tackles exactly that: You write the documentation in explanation order, and the code gets assembled in the order of a well-structured program. Have a look at the examples how this works.
That sounds so painful. Not surprising it never caught on.
Why would it be painful?
You want to turn my 300 lines of clear, readable and concise logic into 1,000 lines of English paragraphs that break up the functions of my code into yet smaller pieces of code devoid of context? Now I have to dig through that book, ignoring all the shit I’ve read hundreds of times because it doesn’t compile into anything, just to debug an off-by-1 error in a loop buried in a paragraph explaining the original developers diatribe on why we’re looping over that range? Fuck. No.
This is the sort of academic crap that sounds good but in practice is just terrible for anything other than small projects that are intended specifically to teach.
Not GP, but reading gnarly code and making definitive statements about who/what/when/where/why such that your documentation is accurate, especially in a corpo context where there are not clear boundaries of responsibility, requires quite a bit of brain power. Not to mention the ever increasing entropy in systems driven by profit means that whatever you write in terms of documentation will have a pretty short shelf-life. The code might stick around as an unholy amalgamation of copypasta after a refactor or two.