Re: Getting the info from the Apple documentation -- Re: New Cocoa w/ CoreData book
Re: Getting the info from the Apple documentation -- Re: New Cocoa w/ CoreData book
- Subject: Re: Getting the info from the Apple documentation -- Re: New Cocoa w/ CoreData book
- From: Christian Stieber <email@hidden>
- Date: Thu, 20 Apr 2006 10:34:58 +0200
At 00:45 20.04.2006 -0400, Scott Anguish wrote:
- they are not able to find the relevant answers in the doc?
(just a
search issue, or a categorization issue)
This is the main thing, probably. The search function is
just completely useless unless you know what you are
looking for, so I always end up randomly clicking along
from known starting points and inventing potential
search words, in the hope of stumbling across a hint
to pursue. Sometimes it works, more often it doesn't.
- they aren't able to understand what is in the doc? (writer's
failure)
- the answer isn't in the doc?
That's the same thing, in most cases. Just yesterday I found
another *typical* useless piece of Apple documentation. I'm
currently trying to use bluetooth (currently researching why
the delegate doesn't get any information about the writeAsync
on an rfcomm channel...). So there I was, trying to find
information on the delegate stuff. Now, what does the doc
explain? It says something along the lines "you can use
a delegate to receive notification about things like this:"
[BluetoothObject setDelegate:DelegateObject];
Now, isn't that a great example? It answers all the questions
one could ever have about using a delegate with the Bluetooth
classes. Do I need to mention that the same documtnation fails
to document the methods that are called on the delegate? It's
easily guessed from searching through the headers and guessing
that the params mean, but still...
Apple just loves to state the obvious, and often fails to
describe the important things. And it's not always easy to
discover things. My theory is that whoever writes the docs
doesn't have a clue either --- which is why the obvious things
are repeated 500 times and the interesting things aren't
mentioned.
Along similar lines, Apple often fails to desribe how things
are supposed to fit together. It's all fine if you just need
the obvious, but thanks --- I usually turn to the docs
when it's NOT obvious how to do things, but they only mention
the simple stuff.
Another favorite of mine is Apple leaving out a tiny,
"unimportant" detail --- occasionally I feel like Apple is
explaining how to drive a car by describing how to turn the
wheel and use the pedals. So I'm sitting in the car, hitting
the pedals and turning the wheel, and nothing happens --- because
Apple never mentioned that you need a key to get the thing started
(my favorite example is the documentation of forwardInvocation,
which has a lot of code stating the obvious, but completely neglects
to mention that methodSignatureForSelector: must be implemented
as well for this to work).
In many cases, instead of useless examples showing how to type
code (thanks, but I know Objective-C syntax) I would much rather
prefer documentation that mentions the facts. In fact, in many
cases the "prosaic" documentation is completely useless, since
it only mentions a few methods that are better explained in
the class documentation, but neglects to explain how things
are meant to fit together. So it's a "cut down the class docs
to the absolute minimum or less, put lots of useless smalltalk
around it, and call that 'docs'".
Basically I'm wasting a lot of time trying to discover how to do things,
and I'm pretty sure that I don't always find the "correct" way. As for
bluetooth, I'm now trying to set a listener instead of a delegate, and
the next step will be to spawn a thread to see if it's related to
runloop modes. Another open research project is sorting of tableviews...
which I didn't even think about originally since I thought I could
just tell the stupid thing to sort it's rows based on column contents.
These (and other things) are completely stupid research tasks that
shouldn't ever come up with decent docs, and it's taking days and
days and more days.
Do I feel better now? Not sure...
Christian
_______________________________________________
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