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: Ondra Cada <email@hidden>
- Date: Thu, 20 Apr 2006 23:25:02 +0200
Christian,
perhaps we use a very different documentation, it would seem?
On 20.4.2006, at 10:34, Christian Stieber 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.
I guess not.
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.
Searching for what you need (instead of "randomly clicking along ...
and inventing potential search words") would be, one can suppose,
much more efficient. At least, I use this approach very contentedly
and with great results for years (and has thus been thoroughly vexed
when Apple trashed Digital Librarian giving nothing useable
instead!). Nowadays though, Xcode offers full-text search
capabilities at least on a par (rather exceeding) Digital Librarian,
so there's no problem at all.
Well, the problem might be if you really do not have an idea what you
are looking for, but that can be hardly helped by any documentation
on earth :)
- 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
I've never ever used bluetooth before. Just for the fun, I've
searched the docs in Xcode; it took me roughly ten seconds to get to
"Working With Bluetooth Devices".
Firstly it should be strongly pointed out that this is a very
**atypical** piece of Apple doc, since it does not document classes
in the standard way. Well, that, I guess, comes with the explicit
disclaimer at its beginning: "This is a preliminary document for an
API in development"!
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];
Still, throughout the document there are links to "Using Delegates to
Receive Asynchronous Messages" chapter (of the "A Collection of
Specific Tasks" document), which describes the six delegate methods.
I haven't checked them, perhaps there are others, but regardless the
docs are preliminary and incomplete, there *is* a description, and is
*extremely easy to find if you half-try*.
... Do I need to mention that the same documtnation fails
to document the methods that are called on the delegate?
Good you haven't mentioned it, for it does.
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.
My experience with the documentation I've got in /Developer/ADC\
Reference\ Library very much differs. It is great.
My theory is that you haven't a clue of using them great docs, and
that's the real problem.
(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).
Try this exercise:
(i) open the Documentation window;
(ii) choose API Search method;
(iii) enter "forwa" into the field;
(iv) select the very first hit (forwardInvocation: method of NSObject);
(v) read the *emphasized and boxed* note, which says:
"Important: To respond to methods that your object does not itself
recognize, you must override methodSignatureForSelector: in addition
to forwardInvocation: ...."
And so forth. I think this is not worth the time spent :)
The documentation of course is far from perfect--no documentation
ever was or will be. But is *extremely* good, e.g., compared with the
utter cr** of standard Sun's Java documentation, which one absolutely
cannot find his way in. Matter of fact, I've hardly ever bumped into
such an excellent documentation the Apple's is.
Do I feel better now? Not sure...
Same here, I guess...
---
Ondra Čada
OCSoftware: email@hidden http://www.ocs.cz
private email@hidden http://www.ocs.cz/oc
_______________________________________________
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