Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: "Andy O'Meara" <email@hidden>
- Date: Mon, 04 Jul 2005 21:13:11 -0400
Some of your points may hold a bit, but it doesn't seem like you've given
Apple's sample code db a fair shake -- there's a landslide of great,
reusable sample code on ADC. If you're new to it, use have the ADC be your
starting point for everything (http://developer.apple.com/). I recommend
you use the ADC as your main go-to page when it comes to getting help (I
only use the local docs when I don't have an internet connection). Finally,
Apple's tech notes (http://developer.apple.com/technicalnotes/) are usually
pretty invaluable (and underrated, imho) when they happen to relate to what
you're doing (although I wish they'd have more sometimes).
Beyond that, you'll be hard-pressed to find better documentation (so I'm
thinking you haven't taken a thorough look around in ADC?). One of the
things that *kills* me about msdn is the total lack of sample code--I always
have to google around to find an example of a MS technology. At ADC, they
have at least one sample project for every possible suite and all their
example projects are usually pretty complete (not just one page of code that
is worthless). Granted, I could be suffering from a distortion field, but
I've always regarded apple docs as the most well written and edited docs
around.
Andy
On 7/4/05 8:27 PM, "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 picked up the book "Learning Carbon", installed Xcode and was on my
> way. I learned how to create a window and show it. Life is dandy.
> However, now I'd like to see all the things I can do with my newly
> found WindowRef. How do I close it, move it, add transparency to it,
> make it spin around in circles, etc. So I fire up the documentation.
> I click on Carbon....
>
> And now I'm lost. Window, hmm, is that Fundamentals? Click. Nope,
> doesn't seem like it. Doh, why doesn't the back button on my mouse
> work like it does in all the other OSX apps. K, I guess I click this
> little back arrow thing. Wait, that's not the page I was on before,
> where did this page come from. Grr, this is getting annoying.
>
> K, let's try API reference, that sounds good. Click. Hmm, am I
> supposed to wade through all these topics trying to find the one that
> pertains to me? And why are they organized by date instead of topic
> or something?
>
> K, maybe I'll search for ShowWindow instead, maybe they link to all
> the other functions from there. What, why didn't the function
> ShowWindow jump to the top of the list? Certainly seems like it would
> have a high relevance. Oh, I see, search by API, K, found it. Hmm,
> okay there's a few functions here, but surely that can't be all of them.
>
> Let's see the cookie trail indicates that Window Manager Reference
> might be a nice place to look. K, looks like this might be more
> interesting. Looks like groups of functions are organized by topic, I
> guess I can deal with clicking each one to see summaries, but it sure
> would be handy to have a whole list.
>
> K, ShowSheetWindow, that sounds like what I'm looking for. Now, how
> do I use that? Hmm, takes two WindowRef's, okay, I know how to get
> those. Hmm, does it just show it for me or do I need to provide some
> sort of event handler for it. Maybe I need to setup all that stuff
> ahead of time just like a regular window. Boy a small snipet of code
> here would really do the job, then I could just copy & paste code
> that's probably boilerplate stuff and used a lot. It'd be real handy
> to know when to use a sheet to, didn't I see that info somewhere
> else? Hmm, no link to any usage details or user interface guidelines.
>
>
> My example here is kind of contrived, but I hope it shows what I'd
> like to see in the documentation. I've spent a fair number of hours
> in the last couple weeks trying out small apps in Carbon and Cocoa to
> get a feel for the development process. The documentation has been
> the most frustrating aspect of this process by far. I'm not a full
> time OSX developer, so I have many, many languages and APIs I need to
> keep in my head (which is a small finite space). I need all the help
> I can get (code completion will be my next email :-)
>
> Also hurting the documentation is the limited amount of web
> resources. I pray every night that Apple will setup/sponsor a site
> like www.codeproject.com for Carbon/Cocoa/etc. If that was done, then
> people from all over could contribute small code snipets.
>
> Thanks
> Bill
>
>
> _______________________________________________
> 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