Another concept I've been ideating about is how to bring Literate Programming, by Donald Knuth, into my daily work, which involves modern tools and stacks like VSCode and Node.js. I believe inline, rich text snippets which are integrated with some kind of personal knowledge management system is the way to go. This way, instead of having comments like this: // TODO: Refactor this to use the revised approach It instead would look like using Notion or Obsidian inside VSCode. So above a function, would be a small window into a single page that describes a single function. You can do anything here, like linking references that are relevant to the design of the function. Or you could even have a lengthy design document that explains why a function was written a certain way. Going even further, you could have a page which describes the evolution of a function over time, why at the beginning it was written a certain way, why changes had to be made, and why it looks the way it looks right now. And added bonus of this approach is that now it's possible to have a single source of truth for docs and your code. So rather than maintaining a separate Docusaurus that has to be updated to sync it with evolution in code, you can just maintain documentation in line. And then to publish developer docs online, you merely just take all the little snippets above each function and then aggregate them onto a single page.

To expand on this - can we also use hyperlinks to represent links within the code itself? Eg if you have a type annotation

a: TheType

, then

TheType

is not a piece of text but a hypertext link to the type definition. These would be resolved at edit time. Same with method calls that can be resolved. Dynamic dispatch / abstract classes can be represented by a link to the base definition.

That'd be useful. It'd be a type of transclusion then. Instead of having to refactor the class name, or type name, whenever you edit the name, it's editing all instances all at once.

I suppose you could write a special editor for doc comments that would spit out markdown or something.