But since the NeXT folks showed up, Apple’s documentation has gotten remarkably worse–and in the past few years there have been no attempts to fix the problem.

Okay, here’s a question for anyone who knows Cocoa: what is the lifecycle of a NSWindow? I mean, sure, you can create a NIB representing the contents and it just “magically” appears–but who is the guy behind the curtain? How does the “magic” work? And how is it supposed to work?

There was a time when Apple’s documentation would give an introductory couple of pages about each logical unit of execution–each “toolbox manager”–which talked in some depth about how something would occur, and which routines would be called to make it happen. If there was a resource-driven initialization routine, the documentation would explain what non-resource driven routines were being invoked and how things were being wired up–so that, when we did use the resource-driven routines, there was a certain sort of “sense” to it all. We were not writing to a black box: we had a mental model of how things worked under the hood, even if some of that mental model was not completely accurate. After all, we may not have carburators anymore–but something mixes the air and vaporized fuel together to explode in the cylinder to make the engine turn over.

And my biggest obsticle to learning NeXTStep, er, ah, Cocoa, is that I don’t have the 10 years of history watching the system evolve to understand what it evolved from–as I do with the Win32 API. So I don’t have a mental model as to how it all hangs together–and Apple’s current sorry state of documentat sure the hell isn’t helping.

Some parts of the documentation do help. The Event Handling Overview sure helps. But figuring out how a Window goes from an idea to something I’m interacting with on screen–well, it’s not like the the NSWindow class overview is of any help. Two hundred plus methods, and the documentation sucks even worse than a JavaDoc dump–if that were even possible. Two hundred plus methods, and two fucking paragraphs of introductory material which state the obvious–and nothing else. Nothing on how Windows get built–nor even a mention if it is even possible to build an NSWindow without using a NIB.

*sigh*

Somehow Apple assumes from this I’m supposed to gain some sort of understanding. Yeah, right. An alphabetical dump of 200 methods with a rough grouping by “function” doesn’t exactly constitute transmitting a fundamental understanding.