Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Guy English <email@hidden>
- Date: Sat, 9 Jul 2005 02:47:00 -0400
On 7/9/05, Raffael Cavallaro <email@hidden> wrote:
> Documentation should be geared toward those who don't
> know what the docs contain. After all, if you already know what they
> say, you wouldn't be consulting them.
Well, I agree - but the API reference is just that: reference. Example
code belongs in the supporting documents. Cross indexing the API refs
with articles and sample code would be beneficial here I think though.
> But at least the API
> references have enough meat to allow one to figure out what the
> relevant sample code would look like if it existed.
You would have loved the Good Old Days Of "Description Forthcoming"
when you wouldn't know what something did and you *liked* it like
that. :)
Cocoa was a leap for me when I started and I think most more
experienced Cocoa devs will tell you the same. After the "click"
things just seem so much more obvious and docs start to make a *lot*
more sense. Note that this isn't meant to be some kind of perverse
test or arbitrary barrier it's just the truth. The nature of
Objective-C is vastly different from the languages most people are
experienced with and Cocoa leverages this is a growing number of
interesting ways. The frameworks work and work well, the docs do a
much better job of explaining them than they ever have in the past,
the critical leap is, however, what it's always been - internalizing
the "culture" and design patterns. Once you get there a lot of things
become second nature even if you haven't done them before. I know that
sounds like a fan-boy think to say but I think it's true enough.
Later,
Guy
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden