Author here. Looks like we both have a similar length of experience. I wouldn't give up this battle yet, because
> Firstly you cannot please everyone
> And secondly, programs are not structured for pedagogy
My theory is that you only need to please a couple of maintainers that work with you, not everyone. That's why I proposed a test with 2 colleagues at the end. It could potentially be spiced up with 2 colleagues of different levels. I believe this can act as one of those 20% effort to get 80% there, but definitely don't claim to have proof of this.
I am also on about the same timeline as you and GP, and in my humble experience, it's really just about having a lot of code/prose "under your fingers", so to speak.
I can't remember where I read it, but the wisdom I heard for writing is that until you've written a million words, your writing won't be worth reading. This feels to me like the 10,000 hour rule.
Code has the added problem that the reader must have additional fluency in it on top of human language, plus a whole bunch of idioms that may or may not be in vogue, or mayhap haven't been seen outside the organization they originated from (think silos; copyrights, secrecy and only getting binaries really don't help here). In some respects, we have code written by Chaucers, but is only from 50 years ago.
I do agree with you that Pareto principle definitely applies, but wherever possible I try to make my code as understandable as possible, with comments and ancillary documentation showing the "why". What I really wonder, is where are the world-class codebases we can point to as exemplars of what readable code looks like? Who can we cite as masters of the craft that make code others understand easily? Is Knuth one of them?
One codebase that I liked in terms of these qualities (albeit I'm sure it's not 100% perfect) is Redis[1]. There are YouTube videos[2] of antirez walking through it. Would love to find more examples too.
> Firstly you cannot please everyone
> And secondly, programs are not structured for pedagogy
My theory is that you only need to please a couple of maintainers that work with you, not everyone. That's why I proposed a test with 2 colleagues at the end. It could potentially be spiced up with 2 colleagues of different levels. I believe this can act as one of those 20% effort to get 80% there, but definitely don't claim to have proof of this.