Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Tom Blenko <email@hidden>
- Date: Sun, 10 Jul 2005 13:37:53 -0700
DigitalLibrarian. Some of us use MTLibrarian as a replacement for DL on
OS X. It does the job and, while it's had some bugs, it's way more
reliable than DL was. (DL did not improve over releases).
I guess something could be built on top of Spotlight to support similar
functionality.
I requested something like this from the documentation group at Apple,
as a feature of ProjectBuilder/Xcode, some years ago. There is better
support in Xcode now but remains at a low level.
There is a pretty good search facility if you go onto the developer
site.
Tom
On Jul 9, 2005, at 12:09 AM, Carlos Salinas wrote:
I can see where there is a lot of information about obj-c, and I can
see where it'd be hard to organize It' not just what is written, but
the way it's organized on the site.
If you have suggestions for organisation that you think would make
things easier, please let me know.
Back in the day (NeXTSTEP, a decade ago now) we had a simple
application that you could use to search through all the
documentation, all the example code, all the header files, and other
folders (such as your source code). The hits were presented in a
simple, clean list - no gobs of white space between rows or organizing
goop. In the same window below that list was a text field. Selecting
an item in the list displayed the matching document in the text field
below. Simple. Dumb. Stupid. Yet it worked well. One could type in
setIsVisible: and find every single documentation reference, the
header declaration, every example code reference, and every use in
your own code and then quickly and easily browse through all those
hits to get a better understanding of how that method worked. Now we
have gobs and gobs of complexity and nothing I've found matches the
simplicity or utility of that older solution.
Something I expected would be in one section is instead posted in
another. It's just hard to find things in most cases, and some
pages are utterly useless they have 2 paragraphs of 3-4 sentences
that really don't tell you anything, even in some of the docs for
specific objects, you look at a method, and look at it's
description, and your like "WTF does that mean?". It's just bad.
When you find cases like this, please file bug reports.
The QuickTime documentation is a good example of documentation
fragmentation. (The function documentation itself is great, better
than Cocoa because each parameter is described, the function itself is
discussed and the return value is mentioned.) The QuickTime
documentation is fragmented because each function, type and constant
are presented on separate web pages. That makes it harder to grok the
entire API. The thing about documentation is the knowledge that is
picked up serendipitously while looking for something else. When
several functions are on a single page, I might start looking for
function XYZ and end up browsing across the much more useful function
ABC. Fragmenting the documentation restricts those discoveries.
A similar thing happened to the Cocoa documentation. Originally the
classes had large and extensive descriptions. You might start looking
for one method and end up learning a lot more about the class because
the description was on the same page. But now the description has been
broken out into a separate page and that makes it harder to learn
about the class.
_______________________________________________
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
_______________________________________________
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