Literate programming, as a concept, is super interesting. But it has a fundamental problem, when applied to software-as-an-industry, that I think is difficult t

Literate programming, as a concept, is super interesting. But it has a fundamental problem, when applied to software-as-an-industry, that I think is difficult to solve: many, if not programmers, may be literate but are not literate enough. If you go look at a Knuth example of literate programming, there emerges a few fundamental capabilities. One: the ability to look at code fresh, as if it were to someone wholly unfamiliar with the module or function in question. And to do so without leaping to the smarmy-tech-nerd "I understand it so this is easy" thing--we're talking about a baseline level of empathy cultivated so as to be able to return to the mindset of a novice in order to help them climb from there. Two: the ability to explain, without the prior knowledge of that module (unless you are to reference that module, which has the same rules), what it does and why it matters. In words. Not "the code is the documentation", but words. Three: the ability to do both of the above engagingly enough that people don't go take a nap instead of read it. You don't need to be able to write hot fire, but you need to be able to write. These are difficult things unless you have a decent grounding in the humanities, and even on a place like HN, which self-selects for people who want to write things about stuff, you see pretty serious capability gaps on the regular. (To be clear, I wish it was the answer, I just don't think it is. Not without a fairly radical rethinking of how much humanities matter to software development.)