Writing Literate API Documentation in Emacs Org Mode

I know what you mean. I was paid to write the API, and the documentation, which provided the necessary motivation to try to write it "literate". I had already been using `restclient` instead of Postman to interact with other APIs I work on. It was just a matter of being paid to take it to the next level.

Note that Knuth has written dozens of books and is perpetually making edits and corrections to them (not just typos, but often extensive rewrites while making sure that the book remains coherent as a whole): this is an activity that comes easily to him, so one can see how he can do it with programs too. The rest of us may find it harder.

But then again, we can ask: if we cannot keep the program's document structure as a whole up-to-date, then are we really editing the program properly? A major risk of introducing bugs is that one may edit a part of a program without taking into account the broader context, such that the integrity of the program is lost, and literate programming (which forces us to update "the whole program" every time) can be considered a mitigation of this risk… so IMO the greater time that it takes to update the whole program could actually be a good thing, saving time in debugging or whatever.

Edit: Also, part of the trick is to put only as much as you think is really relevant in the "text" part: literate programming does not necessarily mean over-commenting everything (Knuth doesn't either), it's just an orientation that what you're doing is writing a document. It's ok for most of that document to be code, as long as you think you've presented it well enough.

Yeah, I encountered this difficulty while writing the "literate" API documentation that my blog post was based on. The example in my post is very simplistic. The real thing makes numerous database queries to set up data, then creates an entire mock "client" with a mock employee, mock location, mock services, appointments, etc., by making successive requests to the (local dev) API. Order matters. And it's still a pretty simple example of literate programming (if, as someone mentioned earlier, it could be called "literate programming" at all in the sense that Knuth meant it).

In that regard, I'd say it is. True, we don't tangle and weave to separate artifacts. In fact, it doesn't tangle at all. However, I'd argue that in this case that isn't the point of the program. It's essentially a TUI to build an HTML artifact. Obviously we can't tangle `restclient` source blocks, but nor are we just dumping the results of `restclient` requests. Everything is piped into bash and post-processed by `jq` to clean up the final result for display.

That said, I accept that it's still not really "literate programming". It's literate API documentation.