One of my own projects in this area is a prototype where I made the best possible explanation of a JavaScript library I could: https://glench.github.io/fuzzyset.js/ui/
and also Knuth agreed, and that is why he invented literate programming.
But why literate programming isn't more popular is beyond me.
And shareholders to make money.
I saw this topic brought up in a video I was watching yesterday https://youtu.be/SzA2YODtgK4?t=1519
There are 2 reasons:
1. Programmers and code review tools are not very good at making sure comments and documentation are updated when code is.
2. People see literate programming as primarily for documentation-focused or teaching purposes.
The statistics in the article we're commenting on suggest that more software systems should be documentation/teaching focused, since the "learning the system" phase is where most of the time goes.
I agree. Specifically, it's for teaching my future forgetful self what the hell this bit of code is supposed to do. Especially if waterbed theory appears to apply and it's inherently a juggling act of interlocked complex systems.
One issue with literate programming is that it advertised a single narrative for code. Only code is data, and there are always many narratives about data. This change might look cosmetic, but it is actually fundamental.
In Glamorous Toolkit, beside having multiple views, we also embedded an interactive notebook right in the development environment and through it we tell interactive stories about the inside the system.
Agreed.
I think it was Fred Brooks who argued that the number of bugs in a system correlates with the number of lines of communication between the coders of the system. And that number grows exponentially as you add coders.
Fixing the communication has the most immediate impact on bug count.
Obviously, your method of communication needs to adapt to the subject at hand. Talking about a website design certainly seems substantially different enough than talking about web assembly concurrency semantics to warrant different modifications of English.
It’s no accident the the Glamorous Toolkit has been implemented in Smalltalk; it is part of the flow of Smalltalk culture.
Instead of slumming of trying to make JavaScript, a truly awful language for humans with the most contradictory base library I know of, faults beautifully demonstrated in several presentations, try using an open source Smalltalk, Squeak, Pharo and indeed GT itself.