Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: email@hidden
- Date: Sun, 10 Jul 2005 12:16:40 +1000
My two cents.
Personally I much prefer having *all* the documentation for a given object in a single reference. That's regardless of where each category or protocol method is implemented. When I'm browsing through the docs, I'm looking at how to do something - I don't care about menial details like which frameworks are needed etc. Sure, if I'm writing a Foundation tool and I see a method that requires AppKit, I can't use it, but at least I know that it exists, what's it's requirements are, etc. I can then look at implementing an original workaround, without always wondering if maybe I just missed something.
The docs as they stand are quite unfriendly. As people have said, unless you already know it, you won't have much of a clue where to find it. I shouldn't need to know of even the existance of AppleScript to be able to find setIsVisible in a logical place - the NSWindow reference. Obviously the current NSWindow reference is in the AppKit Reference, which perhaps needs to change, although I think it's sane enough. The base NSWindow is defined in AppKit, ergo it is in the AppKit reference. If I were looking for NSWindow documentation, even as the most newbie coder I would probably have picked up that GUI stuff is in AppKit, so that's where I'd start.
As a related aside, while things like Spotlight and searching in general are nifty on the occasion, they suffer from the same problem - how should I know I need to search for "orderOut" when what I want to do is a "hide a window"? Searching any sort of catalogue is a real specialist area - that's why we still have professional librarians, despite the apparent "wonders" of modern search technology; they already know what's there and vaguely where it is, and know the little "gotchas" like "hide" == "orderOut", etc.
I'd also like to second a few opinions of others:
* More sample code tied into the docs. I agree with others that MSDN is a very good example of this done reasonably well.
* Note changes in behaviour between versions (e.g. bug fixes, semantic changes, etc).
* More thorough documentation in general. It can be really hard, I know, to write good function documentation that will be useful to those using the function - regardless of who's writing the documentation. But in general, keep in mind that the users want to know at least basic things like which parameters can be nil (without it crashing/throwing exceptions/etc), what basic behavioural domains the method has, any obvious gotchas such as whether the method plays with runloops/threads/etc, what sort of state the method expects (e.g. for some sort of "connect" method on a socket, it needs to say it expects an address to have been set using "setAddress:", etc)... and so on. HeaderDoc provides @param, @result, etc... use them!
* Define what actual error codes a given method/function is likely to return. "Returns an error code" is really useless, since I then don't know what to expect, and can't try to code explicit handlers for them - sure I can guess the most logical ones, and probably get 90% of it right, but then there's those nasty edge cases; those errors that come from deep inside some private framework and filter out through a dozen layers of abstraction...
* More metadata, one way or another. The "hide window" example was a good one - however it's done, "orderOut" needs to be the first hit in any search for anything like "hide window". The docs also need to state that orderOut hides the window; to someone coming from any other dev environment, the current docs don't imply that.
Also, I'd like to see less "issue a bug report" and more "yes, we understand". If Apple really have an internal process which requires a bug report before you're even allowed to listen to a problem, then we might as well all jump ship right now. This is bureaucracy people, and it's unnecessary.
But, *but* *BUT*, I have said and will say again that I really like the way the docs are improving over time, given finite resources. Don't get miffed about the negative vibe from my emails and those of others - creative criticism is such by nature, but nonetheless well intended. Thank you for all that's been done so far.
Wade Tregaskis
_______________________________________________
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