Literate Programming
I've converted Chronometrist (my time tracker for Emacs) to a literate Org program, and really appreciate being able to restructure code in different ways using Org headings, tags, and properties.
What was previously a jungle of files, each one difficult to navigate in itself, is now a single file which is easy to navigate. Each definition has been given its own Org heading, tagged with types (function, variable, macro, etc). I now plan to gradually add more type information as Org properties (basically key-values), so a developer can construct more sophisticated temporary views of the code.
Getting an outline of the file fulfils what I needed from a reference document 1 I really like this idea of four kinds of documentation - tutorial, how-to guides, explanation, and reference. , so I don't need to maintain a separate one anymore. 2 Currently I have a user-oriented README containing the tutorial and how-to guides, and the literate Org program becomes a reference document if one reads the docstrings of individual definitions (since this is Emacs, there are also a myriad other ways to look up the docstring of a loaded Elisp program), and an explanation if one reads the Org text. I also like that the explanation documentation takes its place alongside the source, in the same context - no jumping between the two, and one can hide either if desired.
Yet, I wasn't much interested in Tim Daly's proposed aim of "writing a book" instead of a program and its documentation…
…but today, I had a realization of sorts. (It may or may not not be Daly's own motivation for the emphasis on "a book, not documentation", but it does motivate me.)
There's this tremendous body of knowledge possesed by the maintainer/author of a codebase, which is usually put into documentation.
But if others are anything like me, who wants to read documentation? It's not fun.
However, if the documentation was written with the care and work that goes into a book, if it was as entertaining as one…reading it would be less of a chore. People might actually read it. If it's entertaining enough, they might even read it more than once.
Of course, the question arises whether the knowledge is important enough for you to transfer to future maintainers. In other words, "is it worth it?" 🤔
If the program is important enough to you, and you want it to live on, beyond your personal maintainership…then, perhaps, it might just be.