Cocoa mail archive
Re: why are there zero examples in the cocoa docs?!
FROM : Kyle Sluder
DATE : Sat Jan 19 21:13:17 2008
On Jan 19, 2008 2:47 PM, Joeles Baker <<email_removed>> wrote:
> Hi,
>
> or in other words:
> why does the documentation suck so much (for beginners)? :-)
> am i researching the wrong place?
It's not so much that the documentation sucks, it's probably more that
you haven't yet wrapped your head around how Cocoa operates.
I had the exact same reaction that you had when I started. I
literally printed out every guide I could (Core Data, Key-Value
Coding, Document-based Applications...) and read them over and over
again. I found the lack of examples attached to method descriptions
frustrating at first. But eventually I came to the realization that
MSDN-style documentation is unnecessary for most of Cocoa. Almost
everything is implicit, and if not, it's intuitive. You just need to
understand high-level concepts (delegates, model-view-controller,
etc.) to immediately intuit the purpose of most methods. More verbose
documentation (and guides) are usually provided for those features
that aren't covered by this mental model.
I guess it's a roundabout way of saying that learning Cocoa isn't
about looking up contracts in the manual, it's about hammering at,
tearing down, and rebuilding your mental model until it resembles the
actual model of how Cocoa works. That's not to say that the
documentation couldn't stand to be improved; I personally feel that
there are a lot of portions of frameworks that are missing guides,
such as some of the filesystem stuff in Core Foundation. But Cocoa
isn't meant to be written the way PHP, Win32, and even Carbon are, so
it takes a little getting used to how the documentation is written (or
not) as a result.
--Kyle Sluder
P.S.: I wouldn't look to the PHP documentation as an example of
shining brilliance. It is frequently out of sync with the actual
codebase, retains descriptions of functionality deprecated in previous
releases, provides unnecessary implementation details (effectively
turning them into guarantees, when they have no business in the public
interface) and is plagued with people incorrectly (re-)implementing
functionality in the comments section.
DATE : Sat Jan 19 21:13:17 2008
On Jan 19, 2008 2:47 PM, Joeles Baker <<email_removed>> wrote:
> Hi,
>
> or in other words:
> why does the documentation suck so much (for beginners)? :-)
> am i researching the wrong place?
It's not so much that the documentation sucks, it's probably more that
you haven't yet wrapped your head around how Cocoa operates.
I had the exact same reaction that you had when I started. I
literally printed out every guide I could (Core Data, Key-Value
Coding, Document-based Applications...) and read them over and over
again. I found the lack of examples attached to method descriptions
frustrating at first. But eventually I came to the realization that
MSDN-style documentation is unnecessary for most of Cocoa. Almost
everything is implicit, and if not, it's intuitive. You just need to
understand high-level concepts (delegates, model-view-controller,
etc.) to immediately intuit the purpose of most methods. More verbose
documentation (and guides) are usually provided for those features
that aren't covered by this mental model.
I guess it's a roundabout way of saying that learning Cocoa isn't
about looking up contracts in the manual, it's about hammering at,
tearing down, and rebuilding your mental model until it resembles the
actual model of how Cocoa works. That's not to say that the
documentation couldn't stand to be improved; I personally feel that
there are a lot of portions of frameworks that are missing guides,
such as some of the filesystem stuff in Core Foundation. But Cocoa
isn't meant to be written the way PHP, Win32, and even Carbon are, so
it takes a little getting used to how the documentation is written (or
not) as a result.
--Kyle Sluder
P.S.: I wouldn't look to the PHP documentation as an example of
shining brilliance. It is frequently out of sync with the actual
codebase, retains descriptions of functionality deprecated in previous
releases, provides unnecessary implementation details (effectively
turning them into guarantees, when they have no business in the public
interface) and is plagued with people incorrectly (re-)implementing
functionality in the comments section.
