Old Apple Conceptual Documentation
Just found that the old Apple conceptual documentation is still available for offline searches. Extract the .docset from the .dmg and load it in a tool like Dash.
There’s a lot of good stuff in here that has been removed without replacement from the current docs. Opening the package produces an error from the Installer app:
This package is incompatible with this version of macOS.
The package is trying to install content to the system volume. Contact the software manufacturer for assistance.
But you can expand it via Terminal:
pkgutil --expand-full /Volumes/ConceptualDocset/ConceptualDocset.pkg ~/Downloads/ConceptualDocset
Update (2021-06-13): Howard Oakley:
Third-party attempts to document Mac OS X have been brave, but none has stood the pace of change. Amit Singh’s Mac OS X Internals from 2006 was replaced around 2017 by Jonathan Levin’s outstanding trilogy *OS Internals, which was marred only by its lack of an index. But no sooner had Levin completed his series than he abandoned it in favour of documenting Android.
DocC looks exciting, and demonstrates that Apple recognises its problem, at least in part. But it falls into several well-known traps.
First, it concentrates on documenting calls within an API by individual function. For a developer who already understands how that sub-system in macOS works, that’s essential. But trying to grok major topics like Attributed Text simply isn’t possible by referring to individual functions within the API. You first need to get your head around how sub-systems are designed and function, the conceptual information which Apple was once so good at providing. Good conceptual documentation is structured and written quite differently from that for classes and functions with an API, as Apple well knows.
Update (2021-06-18): See also: Hacker News.
From my perspective, I was in SWE at Apple for over a decade, their documentation started going downhill as iOS development ramped up. By the time they got to the yearly release cycle for macOS and iOS documentation was an afterthought. Most was generated with doxygen from inline docstrings.
The reason I think the quality and quantity dropped was the internal schedules barely (or don’t) leave enough time for the engineering work so there’s very little time available for high level documentation. Internally tons of “documentation” existed as Radar comments or exchanges on internal mailing lists. Maybe a group’s wiki had some crystallized documentation or high level architectural descriptions but good luck accessing it from outside that org. My favorite was some discussion about overall design or architecture that got the “let’s take this offline” where all the helpful details ended up shared in an in-person meeting.
The internal secrecy and rapid development pace made it really difficult to get good overviews of technologies internally.
2 Comments RSS · Twitter
Thanks for the tip, very helpful.
I was able to 'install' the package to a user account folder on Big Sur (11.4). I then used Show Package Contents to copy the documents to their final location without recourse to the Terminal.
