I think that underlines a major point, though. CWEB is specifically to document the program for reading. It is not user documentation. It is not a design document of the intent of the system. It is documentation of the code, specifically.
It can be difficult, because the assumption is emphatically not that the reader in unfamiliar with the target language. To that end, much of the code you find in CWEB will still be using idioms of the target language. Can still be somewhat jarring if you are not expecting that.
No you can combine both, which is the preferred way. As an example (although it does not use CWEB, but its own code) LaTeX's .docstrip/doc/dtx system does that. It generates the code, a driver and documentation both for code and user. It also produces an index automatically. You can use it to write your Javascript code if you want. As Wirth or maybe it was Hoare used to say code is literature as it is meant to be read by humans not only computers.
Fair. Though I think it is a safe to say that the intent is to document the software moreso than the use of it. Mainly going off of all of the programs on Knuth's homepage. TeX and METAFONT are both the same. The literate program is distinct from the user manuals.
Have used literate programming for a real-life
freelance project a year ago. Am using it for both
my private projects and current freelance projects.
The manual can be broken down into four parts or
volumes depending on size:
I. User's Guide
II. User's Reference Manual
III. Maintainer's Guide
IV. Maintainer's Reference Manual
Don't get this wrong, updating the screenshots in the
User's Guide is annoying and a pain.
Over 60% of my time go into writing soft
documentation for the users.
This seems to be the best way to have hard evidence
of the gathered requirements.
It shows what the user actually faces.
The user stories write themselves.
This is the place to put assumptions and data-flow
requirements that the human being in front of the
tool has to know.
The customer last year loved it.
Testing becomes easy.
Just follow the pictures in the User's Guide.
That's your checklist.
In last year's project we immediatly found
differences in using the application on iOS and
Android, just because the customer was on iOS and
could play around with everything immediatly [0].
The first working prototype was done in a week.
Iteration was fast in a tight loop with the
customer.
Basically, live coding.
Source code, entity-relationship diagrams made with
Dia diagram, data-flow diagrams and even some math
typesetting go into the Maintainer's Guide.
All those hairy assumptions forced upon you by third
party libraries, external APIs, and external ABIs
go in big fat red boxes.
Ongoing maintenance check-lists, build steps, and
deployment issues also live here.
LaTeX makes it look beautiful.
It is, honestly, a joy to read and nice to look at.
Just like with research papers decent pictures make
it better.
The reference guides are basically lookup-tables.
There can even be an index and a glossary.
The PDFs can even be stored in git(1).
I know, I know, don't store binaries in git.
But it archives the project well [1a,1b].
You already have the screenshots.
You can pull old versions out.
All the hidden footguns can be called out in the
text.
"It is better to solve the right problem the wrong
way than the wrong problem the right way."
-- Richard Hamming as quoted by Doug McIlroy in
Eric Raymond's The Art of Unix Programming. [2]
It can be difficult, because the assumption is emphatically not that the reader in unfamiliar with the target language. To that end, much of the code you find in CWEB will still be using idioms of the target language. Can still be somewhat jarring if you are not expecting that.