The Elephant at WWDC

However, I think there was a mismatch of expectations, since the Apple ][ was documented down to the last bit, including the schematics and ROM source code (excluding the Applesoft BASIC developed by Microsoft).

The creators of the Mac wanted to force developers to adhere to the abstractions Apple provided with the OS and to discourage developers from using low-level tricks. This enabled Apple to evolve the Mac much further than the Apple ][ series. The last model of the Apple ][ series, the //gs, had to provide a lot of hardware to enable backwards compatibility with software written from 1977 on.

In contrast, the Mac survived a relatively pain-free transition to the PowerPC in the '90s, which was one of the first wide-spread uses of binary translation in commercial systems (later used for the transition of OS X to intel and now to Arm) - even significant parts of the kernel were still written in 68k assembler on PPC systems.

Of course, there were some significant problems to overcome in the 68k era. One well-known example is that developers (even Apple's developers themselves) abused the most significant 8 bits of addresses to store data. The original 68000 had 32 bit address registers but only a 24 bit external address bus, so the 8 MSBs were ignored by hardware. This was no longer true on the 68020 and later CPUs and caused lots of problems...

Talking about the state of documentation of macOS, even the old NeXT documentation was better and more in-depth - though there was no detailed information on the hardware, which causes problems for the developers of the Previous emulator today. Of course, the NeXT systems were much less complex than it is today, even though you already had to cope with coprocessors such as the Motorola 56001 DSP and the i860 on the Dimension color graphics card (which unfortunately could not be programmed directly)...

Spent many years as senior dev for a custom Android ROM, yet Levin's book still introduced me to multiple other Android internals I had not yet looked into. Would happily pay 200-300 for his next Android book. Probably not the best books for a total beginner, but if you're already skilled and looking for the next level I would highly recommend.

My only real complaint is that JL seems to do a lot of the marketing/date-setting himself, and it shows. It can be really confusing to keep current on what book he is working on next, what topics will/will not be covered, how to even pay for the book can be a bit complicated (send paypal to this email), etc. It is fantastic that he adjusts and expands book contents as the market/technology changes (e.g. always chasing to get the newest stuff covered in the newest book), but the current end result is a stream of "update" messages on his website that are hard to follow. Would be wonderful if he had someone help him with that "public-facing" side and try to keep things organized/consistent/obvious and hide a bit of "how the sausage is made"

Who maintains these? Most development teams I've met never bother checking the example code works. 99% of the time, they'll write up a presentation, once, click "record" on the video conferencing software, and everyone says "cool, it's documented". And then, 6 months later, half the presentation is obsolete, and it ends up being even more confusing because as the reader, you have to investigate what has changed since this presentation happened.

I've noticed, if you put some real thought behind maintaining these higher level docs, you don't end up with _tons_ of documentation. And the speed of adoption is rapid. But it takes design, a feedback loop, etc. It's really another kind of deliverable, separate from creating a software product itself.

GP said a whole, not the whole.

A subsystem, abstraction, or whatever, works as a whole, not as unconnected pieces, and the code needs to reflect the organization and concepts within itself as a meaningful whole.

It’s not that a software engineer isn’t capable of writing, but more that it’s not their primary responsibility.

I also anecdotally believe that having people in roles like this who are accountable for documentation, design, etc improve the overall product as they provide another layer of review.