Re: A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
Re: A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
- Subject: Re: A documetation suggestion (was Re: Cocoa et al as HCI usability problem)
- From: Steve Weller <email@hidden>
- Date: Fri, 23 May 2008 15:07:29 -0700
The documentation is for the most part oriented around the
implementation of the technologies offered (inside out view) rather
than the solving of the challenged faced (outside in view). For
experts this is no great barrier, because they are already arguably
inside. But see how this trips non-experts up and makes it hard to
find things:
On May 23, 2008, at 3:09 AM, Gerriet M. Denkmann wrote:
Yes. I even can give you a concrete example:
I do seem to remember that there was something to write files and
folders to a CDs using an Objective-C interface.
- entered "disk" into AppKido - nothing except NSURLCache.
- entered "disk recording" into Xcode -> Help -> Documentation -
nothing at all
- entered "disk recording" into Spotlight - got 360 things, about
250 are .html with names like "index-topic0.html" or similar.
Now I start reminiscing about the good old times with Digital
Librarian:
- I would enable the Conceptual Guides or the Reference (or both)
enter my string and am quite confident to get some references (if
NeXTStep 3.3 only would have had disk recording).
- Ok so I open /Developer/ADC Reference Library/index.html and look
at the choices (Note: there is no search offered). "Cocoa" (because
I am looking for an Objective-C interface) or "Storage" look
promising.
"Carbon" is absolutely wrong, because everybody knows that Carbon
contains only C-APIs.
Well, the answer is of course: look under "Carbon" then "Audio" (I
want to backup the data of my hard disk - I am not interested in
burning audio CDs at all) - then you will see the "Disc Recording
Framework Reference" which "Describes the Objective-C and C API for
burning audio and data CDs and DVDs."
Yes: "Carbon", because there also is a C-API; "Audio" because it
also can burn audio CDs.
This took me just now quite some time (almost half an hour?) to find
(even though I have looked for it several times before).
On May 23, 2008, at 2:49 AM, Ken Thomases wrote:
Unfortunately, you've been bitten by a quirk of technical
terminology. Apple consistently uses "disk" with a 'k' to refer to
magnetic storage media, and "disc" with a 'c' to refer to optical
storage media. If you had searched for "disc recording", you would
have found what you needed right away.
Search fails miserably when you don't know what to search for.
Had there been problem-based top level choices not only would the
information have been found sooner, but the error of terminology
either never made or corrected before it became a burden. Examples of
the kind of topics needed for beginners, the things they encounter
very early without knowing how they are implemented:
Disks
Files
Strings
Tables
Windows
Menus
Buttons
Text fields
Fonts
There *are* some top-level topics, but the organization is odd. If I
want to do some Cocoa Networking, do I look at Cocoa > Networking, or
Networking > Cocoa?
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden