Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Brandon Sneed <email@hidden>
- Date: Tue, 5 Jul 2005 11:46:45 -0500
I think what Bill is/was getting at is that there's a need for better
organization in the documentation, and some confirmation on action,
as opposed to how-to-port-stuff.
Not in response to your reply specifically but to the others i've
read, where people are suggesting:
reading the headers instead of the docs
using the adc website instead of what xcode installs
reading the docs for a day or two
looking at samples for a day or two
IMO, all of these are fine work arounds for the time being, however,
none address the problem. Problem being bad organization.
Organizing things into a deeper tree by either association or
relevancy would make navigation easier in general. His example of
the WindowRef / CreateWindow was a good one. 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. 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 top it off, compared to MSDN's CreateWindow function docs, the
CreateWindowFromNib docs are about as brief as one could possibly
be. I'm dealing mostly with Carbon stuff myself, and most all of
the functions exhibit this sort of brevity.
The forward and back buttons work more logically in MSDN as well.
In the docs that come with xcode, if you're in the middle of a page,
click a link, then hit the back arrow, it doesn't take you back to
where you were. You get dumped at the top of a page, and most of
them are pretty long. MSDN has a single page for most everything
and jumps to full urls as opposed to xcode's docs going to labels in
a giant list of functions.
It also should be noted, that MSDN comes with just as many sample
apps as XCode does, contrary to what someone else posted earlier.
And while the full listing of each sample does not appear in the doc
reader UI, the samples exist on disk just like xcode's does. The
big difference is for roughly 75% of Win32 API calls, there is a
small bit of straight forward sample code that one can get to from a
given function's doc page.
I'm not saying "do it just like msdn!", i'm just saying someone
should acknowledge that there's a big deficiency here and for someone
to come up with how to better organize it or tell us its in the works
or something. If you're a gung-ho long time apple developer, it
probably doesn't matter to you, but to people coming from the
dominant platform it could really turn them off all together given
how easy it is to figure out how to do basic things via MSDN in
VS.NET, and quite the opposite in XCode's docs.
I figure if Apple wants people to switch, that would include
developers. To me, XCode is very promising and has alot of nice
things going for it. However, it still has quite a few deficiencies
as well, documentation being a major one i think. The development
experience in general on Mac OS X is lacking I think, compared to
other platforms. Its really peculiar given all the extremely user-
friendly applications that are available for it. Here's my take on
things since i've switched:
- Mac OS X's applications almost always give the impression of being
well thought-out and well designed. XCode's UI is fantastic, but
its missing the ease that i had under Windows.
- Windows applications for the most part stink from a user
perspective, most are kludgey and overly complex. Despite VS.NET's
UI being awful, writing code that works is made extremely easy by the
good quality documentation and automation of common tasks.
I do realize i'm biased to some extent having been a windows
developer for many years, so please don't flame me for that. If
anything, maybe Bill and I are bringing in some fresh ideas. :D
Thanks for listening regardless of the outcome!
Brandon
On Jul 5, 2005, at 11:00 AM, George Warner wrote:
On Mon, 4 Jul 2005 20:27:19 -0400, Bill Nalen <email@hidden> wrote:
Another problem I have coming over from Windows is the documentation
for Carbon/Cocoa/Xcode/etc. Here's my thought process:
I'd suggest starting at "Porting to Mac OS X from Windows Win32 API":
<http://developer.apple.com/documentation/Porting/Conceptual/
win32porting/in
dex.html>.
--
Enjoy,
George Warner,
Schizophrenic Optimization Scientist
Apple Developer Technical Support (DTS)
_______________________________________________
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
_______________________________________________
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