Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Brandon Sneed <email@hidden>
- Date: Tue, 5 Jul 2005 15:06:45 -0500
His [Bills] example of the WindowRef / CreateWindow was a good one.
It was a bad one, because ...
In MSDN for example, one could drill down into the index tree to
the section dubbed "Window Functions",
... in the ADC Ref Lib the terms are "Carbon" -> "User Experience" -
> "Window Manager", which is about the same.
I disagree. In XCode's doc list, click Carbon on the search group
listing.. Then goto User Experience (a little vague perhaps, but ok),
and start going through the list....
This is a sample of what you get....
Apple Human Interface Guidelines (ok)
HIObject Reference (ok)
HIToolbar Reference (ok)
Search Kit Reference (still ok)
Stickies Example (really odd placement)
...
Disc Recording Release notes (???)
Clickable Static Text Item (work around for QA1380???)
... etc.
There's a lot of oddball topics in there. Some of them obviously
get hidden if you select to display Documentation only.. but then as
soon as you come back your selection of Documentation only is
gone. And to put icing on the cake, you have to scroll down the
entire first page almost searching for it. If it were available in
the tree on the left under User Experience and/or didn't default to
having QA workarounds, various examples, etc tossed right into the
middle of it all, i wouldn't have much to complain about.
So then i go into the Window Manager reference, click the Functions
link, and some categories come up.. lets see.. lets go to the one
called "Creating, Storing, and Closing Windows". Where the hell is
CreateWindowFromNib??? Its not in the list. Now it is in "Carbon" -
> "User Experience" -> "Interface Builder Services Reference". I
can see why it might be included in that, but i think it would more
closely relate to the former to your average developer. You're
creating a window. CreateWindowFromResource is in with the Window
Manager reference, so why not CreateWindowFromNib?
or he could type "CreateWindow" into the search field and the
first result would be the function docs.
Exactly what happens if you do an API search in ADC's documentation
without drilling.
No, not exactly. You left out the context from your quote. Here it
is again.
"In MSDN for example, one could drill down into the index tree to the
section dubbed "Window Functions", or he could type "CreateWindow"
into the search field and the first result would be the function
docs. <this is what you didn't quote> From there, he would have a
link to the "Window Functions" section as well as any relevant api's
to the one he was looking at."
To add insult to injurty, just looking in MSDN on that CreateWindow
doc page, there's a link to a small snippet of sample code that shows
you everything you need to do to get a window on the screen. Both
of those are missing from the XCode docs.
I figure if Apple wants people to switch, that would include
developers.
It's the same problem as with the end user part of the OS: how
would you explain the experienced Windows user to just forget half
of her knowledge because with Mac OS the function is done in a
similar but different way, or is just obsolete?
You do so by giving them something better than they already have and
making the re-learning worth the effort. XCode isn't accomplishing
this on the development end. And besides, learning word for mac, or
pages and/or keynote for mac is quite a bit different than doing
development.
Have fun,
Markus
- - - - - - - - - - - - - - - - - - -
Dipl. Ing. Markus Hitter
http://www.jump-ing.de/
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden