Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: mmalcolm crawford <email@hidden>
- Date: Sat, 9 Jul 2005 21:54:11 -0700
On Jul 9, 2005, at 9:09 PM, Andre wrote:
I'm wondering, now, please don't take this the wrong way, but is
all of the Cocoa/CoreFoundation stuff in a database?
When I go to a page for documentation, it doesn't seem to be
WebObjects or some other DB served page...
When I mean, all the Cocoa stuff, I mean, everything, the docs,
examples, Q&A's, Technotes etc...
I have a feeling most of its not... at least exposed to the WWW
The documentation is contained in a database internally -- it's not
clear what value would be gained from exposing the database to the
outside world? The site is basically static content, and there's
already a free-text search engine
MMalcom asked for a suggestion, so here's one... this assuming
somethings, so...
First, take apart all the docs, sit down, and go over and over,
again and again, find replications of the same data, find the
relationships between them, find old stale references and remove them,
I'm not aware that there are any repetitions or stale references?
then organize them logically according to their relations, take
everything, shove it in an extremely well designed database, build
a WO app to organize, abstract, and present those various sources
in a consistent and
easily searchable manner.
Again it's not clear how a WO application would add value here -- in
what ways might the consistency and searchability be improved?
The really great thing about having it in a database is that then
if one adds a category to a class, or a new constant value, when
its added, certain criteria are set by the adder such that when
accessed on the net its all automatically set and viewable.
This basically happens already.
Especially if its a web objects app, then there can be all kinds of
great ways to abstract the knowledge hidden in there. For example,
a specialized WO app could index everything and present it in a
tree view,
just like the foundation/appkit classes org chart floating around,
then in each "entity" the associated
categories, constants, articles, Q&A's could be listed as the
"attributes" so when one clicks it, it goes to the appropriate page...
Another example would be a NSBrowser-like view where one could
search iTunes-like and drill down
by pure constants, classes, methods, etc. Sometimes we aren't
exactly sure what we need to find...
There certainly may be value in adding this to the web site -- and
please file an enhancement request -- but most of this functionality
is already available in what is IMHumbleO a more convenient fashion,
within Xcode's Class Browser (Project > Class Browser).
Also, a spotlight-esqe search could be added to give much more
relevant results than what it gives now...
What would you like in addition to the existing Advanced Search?
Lastly, I think sometimes a problem, especially people that are
delving into areas of limited knowledge,
certain vocabularies need to be explained. For example, if someone
was used to only handling foundation,
might not know what a "key window" is, then if the database had a
dictionary entity, if one added one for "keyWindow" the WO app that
governs page generation would parse the text, and on the next
display, every instance of the text "keyWindow" when moused over
highlights, and when clicked, opens a small window with the
definition and other related infos... and it could do it with any
word, and automatically as definitions are added to the DB.
Again, I think you're confusing feature with implementation. It's
possible today to search for the phrase, "key window":
<http://developer.apple.com/cgi-bin/search.pl?&q="key%
20window"&num=10&site=(cocoa)>
and get what appear in this case to be useful results. It's not
clear that this will always be the case. A better solution would be
to create an actual index, and mark index items in the text. This
process is underway, but it is time-consuming and laborious...
mmalc
_______________________________________________
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