I think this is a good point. I have mostly gained knowledge of software design by doing this, because once I work through a process that might happen in the code, I can infer the reasoning behind design decisions.
I am still learning myself, but so far, reading production code now seems much more valuable than the pseudo code often found in blog posts. They each serve different purposes but I have found myself reading too far into pseudo code when trying to understand a concept can add unnecessary confusion. With production code, what you see is what works.
And that just gave me an idea: programming books that only use production code! It might do less handholding and would certainly be harder to write, but maybe the value would make it worthwhile.
I thought of this, too, but what I decided I wanted was a book that wrote the simplest working version of some useful thing (basic HTTP server, JPEG codec, basic CRUD web app, etc.), explained it clearly, then gradually "hardened" it, version by version, into true (actually in use) production code. Each new version would introduce an issue, possible ways of dealing with it (each with pros and cons), a well-explained choice, the code that implements that choice, and a discussion of the implementation. Then on to the next issue and another upgraded version of the code until arriving at the actual, thoroughly real-world-tested code in use in some popular system.
Working through a few of these would really feel like apprenticing with a pro.
The GP's suggestion of revisiting code reads to me a bit like the mental equivalent of opening a file to read one line, closing it, opening it and fseek()ing, ad infinitum. Works - and I totally get the GP's approach of repeated "passes" distinguishing increasing levels of significance - but in I've learned the hard way that the overall context switching overhead of this particular approach is so immense that my eyes would glaze over long before I took away anything useful. The real answer there is to inhale the overall structure and reach conclusions about what to prioritize. This most definitely requires a good working attention span, something I've only had access to more recently.
As for your idea, what about: pick a project you think highly of, or find a bunch of code you've read good reviews of¹, and write a reference work on it over a period of time. Maybe publish for free, maybe don't.
I suspect (having never done this idea, and only thought about it for a short time) that the initial tendency could be to simply explain what's going on in the code, in the same sense of "but these comments explain what the [well-written] code's already clearly describing".
What would be even better would be to make the reference serve an introductory context, and allow newcomers wanting to understand the code to use the reference as a fast-track guide. (Oh! I actually have a (maximum-difficulty :D) example of what I mean! 1st two paragraphs: https://bugs.chromium.org/p/chromium/issues/detail?id=671498...)
This would obviously be quite a challenge, not just because of the comprehension/study required but because the goal would then be to "get out of the way", as it were, minimizing/eliminating editorialism etc and just providing enough structural "fluff" for people to stay engaged and maintain flow/focus on the topic (which is very tricky for me to do...).
This could actually be a very interesting pastime to consider. Thanks very much for writing your thoughts.
I am still learning myself, but so far, reading production code now seems much more valuable than the pseudo code often found in blog posts. They each serve different purposes but I have found myself reading too far into pseudo code when trying to understand a concept can add unnecessary confusion. With production code, what you see is what works.
And that just gave me an idea: programming books that only use production code! It might do less handholding and would certainly be harder to write, but maybe the value would make it worthwhile.