[stiff]

I don't think the story of literate programming can be of any help predicting how well this idea here can work out.

Literate programming is not "embedding documentation". The main idea was to separate the order in which the code is read from the order in which the compiler sees it, and it embeds the code in the documentation, not vice versa. It was a very idiosyncratic thing, hard to imagine a team of programmers in a typical current commercial setting, developing a nice LaTeX essay around the actual code of the next social network web-app. As the program grows larger it also gets harder and harder to maintain the "story" around it.

[jashkenas]

That's not the "main idea". Originally, it was a part of the suggested way to accomplish the goal ... but the main idea is this:

    > Let us change our traditional attitude to the construction of programs: 
    > Instead of imagining that our main task is to instruct a computer what 
    > to do, let us concentrate rather on explaining to human beings what we 
    > want a computer to do.
    >                          — Knuth

If your program can be read more as an enlightening explanation of the job-to-be-done, and is more oriented toward the human reader of the code than the machine that will execute it, then you've succeeded.

Hopefully, it's clear how a program written in such a way could potentially be beneficial to a large team, trying to understand, modify, and improve it.

[tokenrove]

Right, but it's important to emphasize what stiff was talking about, that the structure of the narrative needs to be oriented towards the human instead of the machine, because so many people don't bother to do this and decide that literate programming just means having LaTeX or docbook comments in your code. That total inversion (the code is in the documentation, not the documentation is in the code) is important. (That said, I admit that most modern languages are so much more flexible compared to C or Pascal with regards the ordering of code.)

[stiff]

It's like saying the main idea in C was to allow writing programs. At this level of generality it is indistinguishable from tens of projects with similar goals, including also earlier ones.

[pseut]

It's also much less necessary with packages, where you can trivially change the order of most of the code is read.