rosyna of unsanity wrote a very long entry about Apple and developers. As someone with 25 years experience on other platforms, but relatively new to the Mac, I have observed good and bad sides of programming on the Mac.
The good side is that many Mac developers very helpful, for instance answering questions in forums. Also, because Mac OS X is a mashup of various technologies, I know some of them.
The bad side is that not so much that the Mac does some things very differently but that Apple’s documentation is barely adequate. When I read it, I sometimes wonder whether it’s written to satisfy their marketing department’s need to be cool and easy to use, rather than my needs as a developer to use it.
Only Macs are computers! To start with, there seems to be an assumption that if you are new to some Mac technology, you’re new to computers in general. For instance, the introduction to Cocoa explains basic Object Oriented design. This poor separation of concerns reduces the documentation’s effective signal-to-noise ratio. Even if I do slog through it, I find I can’t find the useful bits later. Indeed, it is in Apple’s interest to welcome those of us coming from similar yet different worlds. I would like a guide of features unique to apple: what are bundles? aliases? uti? metadata (xattr/spotlight)? Interface-Builder? Cocoa? (etc) Why should I care?
Program to the interface! Rather than explaining what a given problem is, how Apple solved it, and the reasons why it solved it in that way, Apple focusses on describing the interface they provide and giving a few simple examples. This is insufficient to building a mental model of how things work. A good mental model is essential to debug problems or to easily extend the functionality of a tool that almost does what one wants. While I agree that one usually benefits from programming to an interface and not to an implementation, there are times where the cost of doing so outweighs the benefits. The documentation should address both needs.
Mac software is perfect! Not. Mac OS X has some fairly basic bugs. For instance NSURL doesn’t always parse URLs correctly… It would help to have links to distilled bug-reports in the documentation, so that one can decide whether using an Apple API is appropriate or not. Instead, because bugs are in an unrelated ADC only system (radar), I have only found about them after encountering them. For instance, I am now rewriting my search code to use Spotlight’s Carbon. This results in having had to reimplement things due to a third party (apple) more often than I ever had to on any other platform (including Windows!).
Memory Management! You’re supposed to just know when to free memory. It turns out that there are rules for Cocoa and for Carbon. Nevertheless, other platforms do things differently, and it would help mac immigrants if this information were linked to relevant APIs.
Good documentation is essential to program in a closed source such as Mac OS X. Linux documentation may not always be perfect, but I’d prefer getting a headache reading source code than getting a headache fishing with google. At least I know I will understand the source code, and I might even learn something.
Obviously the good aspects of the Mac outweigh the bad, or I would program something else. But, Apple could definitely improve its developer documentation.