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.

All fine points. I don't think it could work like that haha.

Maybe it could just merely point to real-world examples, without so much detail. I dunno.

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.

¹: INCOMING: https://news.ycombinator.com/item?id=9899766 https://news.ycombinator.com/item?id=13854431 https://news.ycombinator.com/item?id=9896369 https://news.ycombinator.com/item?id=14462125 https://news.ycombinator.com/item?id=8573291 https://news.ycombinator.com/item?id=327710 https://news.ycombinator.com/item?id=1770662 https://news.ycombinator.com/item?id=12381609