The CWEB System of Structured Documentation

I studied CWEB when I did computer science in the early 1990s (eek!).

While it is a way to document and compile your programs from a single file, it still contains the problem of where the story of a program should happen, and in keeping the documentation and code in line and up to date with each other.

It should also be understood that the documentation is for other programmers and not users, since the printout of the document includes the code in-line.

Fraser and Hanson wrote a compiler as a book, using noweb:

https://a.co/d/4ctR3vW

Counter-example.

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]

[0] [James Hague: Documenting the Undocumentable](https://prog21.dadgum.com/161.html)

[1a] [Archive Your Old Projects](https://arne.me/articles/archive-your-old-projects)

[1b] [Archive Your Old Projects (HN)](https://news.ycombinator.com/item?id=38239358)

[2] [Solving the right problem](https://www.catb.org/~esr/writings/taoup/html/ch01s04.html)

isn't the first problem of documentation is keeping it in sync with the source code? Time and time again people come up with "better ways of documentation" while neglecting this basic problem, what problem do they think they're solving?

Do you have a link to your repo where you've done this?