There’s a big difference between macOS and open source projects mentioned to frequently have superior documentation: openness. I’m not inclined to invest my time into learning and documenting a proprietary system owned by a corporation. I don’t whant to have my knowledge made irrelevant by a whim of a sales driven company.
I strongly disagree with this from a business standpoint. Sure, MacOS might be better documented by some collaborative effort but it very well may not be supported. Collaborative documentation ends up describing the current state of systems and processes instead of the intended flow. Documentation is a pseudo-contract between consumers and producers where consumers know what to hold producers to and producers know what they must provide to consumers. By pushing the documentation to only the consumer side, you start seeing documentation that solidifies bugs into something people start depending on because that is how it was documented. When that bug gets fixed, all of a sudden, you have nothing to point to that says you were allowed to use it in that way. Fundamentally, it doesn’t solve the problem that there is no support provided by the producing side and we are just pushing the problem a little further down the investment pipeline.
I don’t agree that macOS is poorly under documented. It actually has a ton of high quality documentation for both end users, power users and developers. But like any other project that size, there are of course gaps. File bugs for Apple to address those.
It is also unclear what the author is really asking for. He mentions the dock and charging a Magic Trackpad. Both have great documentation. The first online and the second both online and on paper.
The author references Inside Mac, which was awesome for old Mac OS. But it was also not complete. And it was heavily focussed on developers. I am going to say that the current Cocoa/Foundation/POSIX documentation is probably as good as what we had with Inside Mac. Better, the current documentation are updated frequently, while Inside Mac was an on-paper static reference that was only updated infrequently.
What is the expectation here? Is documentation hard to find? Does discoverability need to be better?
There’s an argument to be made that macOS is better documented from an average user point-of-view. There are extensive reviews of every piece of UI on macOS and the Knowledge Base articles written by Apple are more detailed instructions on how to use hardware/software than I’ve seen within any individual tech company.
When are we going to see the 20 page review on the next update of Ubuntu? The Arch Wiki is known to be the best source of Linux documentation because all other sources are lacking.
The main problem with Apple’s Unix utilities has less to do with documentation than it has to do with the utilities themselves. If Apple isn’t keeping their utilities up-to-date with mainstream then why would they document those utilities?
Related to the article, but only tangentially:
Is there any documentation for the entirety of Carbon? I know it’s discontinued or deprecated, but say you wanted to write a MacOS X application in pure C, where would you look?
My information is at this point about seven years out of date (the last time I worked on Carbon API at Apple), but the answer is: no. There is not. There is not external to Apple; there is not internal to Apple. There is samizdat that is passed around in well commented header files and copies of old MPW projects, but that’s about it.