Re: The challenge for Cocoa's on-line documentation
bindings is discussed in the Cocoa Bindings Reference the UI settings alone don't take into account all the usage patterns. although there is no question that documentation could always be better (and that's coming from someone in techpubs). On May 17, 2008, at 4:16 PM, Johnny Lundy wrote: - Interface Builder User Guide ignores the dozens of checkboxes and popups that appear in the Bindings panes and instead rambles on for pages about rarely-used features. ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
Re: The challenge for Cocoa's on-line documentation
I never had any problem with a language's documentation since 1970 with the IBM 360 Reference Manual. That is, until I came across Apple's documentation of Cocoa. I have never been so frustrated in my life. - Everything is defined in terms of something else. - Interface Builder User Guide ignores the dozens of checkboxes and popups that appear in the Bindings panes and instead rambles on for pages about rarely-used features. - Examples always say Your code here when My Code Here is what I wanted to see. The usual pattern for a User Guide Reference Manual is for the User Guide to have chapters corresponding to the areas of the product, and the Reference Manual having a page or so listing all the details of each element. The Apple docs have neither. Like this: - tag Returns the tag. See also : setTag Great. Now if only I knew what a tag was Try looking at the documentation for NSDatePicker if you want to see how NOT to write documentation. On May 17, 2008, at 9:17 AM, [EMAIL PROTECTED] wrote: Re: The challenge for Cocoa's on-line documentation ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
Re: The challenge for Cocoa's on-line documentation
On May 17, 2008, at 4:16 PM, Johnny Lundy wrote: I never had any problem with a language's documentation since 1970 with the IBM 360 Reference Manual. That is, until I came across Apple's documentation of Cocoa. I have never been so frustrated in my life. snip The usual pattern for a User Guide Reference Manual is for the User Guide to have chapters corresponding to the areas of the product, and the Reference Manual having a page or so listing all the details of each element. The Apple docs have neither. snip - tag Returns the tag. See also : setTag I do not know where documentation you saw this, but Apple's documentation for NSControl states the following in the method description for tag: Tags allow you to identify particular controls. Tag values are not used internally; they are only changed by external invocations of setTag:. You typically set tag values in Interface Builder and use them at runtime in your application. When you set the tag of a control with a single cell in Interface Builder, it sets the tags of both the control and the cell to the same value as a convenience. That seems pretty darn clear and concise to me. It says something equally clear in setTag: Besides, tags are a fundamental concept in Cocoa. If you don't know what tags are, maybe the API isn't the right place for you to be spending your time right now. I'm sure most of us here don't want to read through a description of what tags are every single time they're mentioned in the documentation. Jeff ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
Re: The challenge for Cocoa's on-line documentation
Johnny Lundy wrote: Try looking at the documentation for NSDatePicker if you want to see how NOT to write documentation. Uh, are you talking about THIS web page? http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/Classes/NSDatePicker_Class/Reference/Reference.html I haven't ever used this class, but from just looking it over quickly, it seems like it's pretty easy to figure everything out. If you have a problem, just click on the links (e.g., NSDatePickerStyle). Okay, maybe not everyone took shop class in high school, but if you don't know what a bezel is, fire up Dictionary! And, if you have a problem with what a background is...well, that's just crazy talk! ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
Re: The challenge for Cocoa's on-line documentation
Am 17.05.2008 um 23:42 schrieb Gary L. Wade:
I haven't ever used this class, but from just looking it over
quickly, it seems like it's pretty easy to figure everything out.
If you have a problem, just click on the links (e.g.,
NSDatePickerStyle).
While I think the docs aren't as bad as some people make them out to
be, I think there's a lot of room for improvement. They rely too much
on clicking links and reading referenced information to put stuff
together. Let's take NSDatePicker as an example:
datePickerElements
Returns the receiver’s date picker elements flags.
- (NSDatePickerElementFlags)datePickerElements
Discussion
See “Constants” for a description of the possible values.
Availability
• Available in Mac OS X v10.4 and later.
See Also
• – setDatePickerElements:
Declared InNSDatePicker.h
It's not at all obvious from this what a date picker element would be
and why I'd need flags for them. If you've played with the date
picker in IB, you'll understand is, but from the docs alone, 'element'
is way too generic, and should be replaced with actual information
instead of just putting spaces in the method name.
Once you click the link 'Constants', though, it becomes clear:
It's not at all obvious from this what a date picker element would be
and why I'd need flags for them. If you've played with the date
picker in IB, you'll understand is, but from the docs alone, 'element'
is way too generic, and should be replaced with actual information
instead of just putting spaces in the method name.
Once you click the link 'Constants', though, it becomes clear:
The NSDatePickerElementFlag constants allow you to specify the date
and time elements that the NSDatePickerCell can edit by combining
these constants using the C bitwise OR operator. These values are used
by datePickerElements and setDatePickerElements::
enum {
NSHourMinuteDatePickerElementFlag = 0x000c,
NSHourMinuteSecondDatePickerElementFlag = 0x000e,
NSTimeZoneDatePickerElementFlag= 0x0010,
NSYearMonthDatePickerElementFlag= 0x00c0,
NSYearMonthDayDatePickerElementFlag= 0x00e0,
NSEraDatePickerElementFlag= 0x0100,
};
typedef NSUInteger NSDatePickerElementFlags;
Of course you wouldn't want to duplicate all information, but I'd
still re-phrase the description for datePickerElements a little:
Returns a set of flags indicating which visual elements of the date
picker are currently shown, and which won't be usable because they are
hidden.
The simple word 'visual' already clarifies the word 'elements' a lot,
and the mention of shown, hidden and usable hammers home the point
that this view consists of different parts that can be activated and
deactivated at will, without mentioning any of the flags and thus
risking to become outdated as soon as someone adds (or, theoretically,
removes) one of these flags.
Cheers,
-- Uli Kusterer
The Witnesses of TeachText are everywhere...
http://www.zathras.de
___
Cocoa-dev mailing list (Cocoa-dev@lists.apple.com)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com
This email sent to [EMAIL PROTECTED]
The challenge for Cocoa's on-line documentation
Johnny Lundy wrote: I never had any problem with a language's documentation since 1970 with the IBM 360 Reference Manual. That is, until I came across Apple's documentation of Cocoa. I have never been so frustrated in my life. - Everything is defined in terms of something else. - Interface Builder User Guide ignores the dozens of checkboxes and popups that appear in the Bindings panes and instead rambles on for pages about rarely-used features. - Examples always say Your code here when My Code Here is what I wanted to see. The usual pattern for a User Guide Reference Manual is for the User Guide to have chapters corresponding to the areas of the product, and the Reference Manual having a page or so listing all the details of each element. The Apple docs have neither. Like this: - tag Returns the tag. See also : setTag Great. Now if only I knew what a tag was I search in the documentation window of Xcode and – after 5 to 10 seconds only – find the explanation. I have followed these threads, and I have a question to you – without intending any insult: Why didn't *you* do this search? (Or did you? But then ...) There should be a reason. If you tell the reason here, all these experienced and ... ahem ... well ... yes ;-) ... gentle people should be able to help you out of *this* – I think: basic – problem. Back to lurking Klaus ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
Re: The challenge for Cocoa's on-line documentation
On May 16, 2008, at 5:05 PM, Erik Buck wrote: [Re-post from http://www.cocoabuilder.com/archive/message/cocoa/2007/8/20/188026 ] That was well worth reposting. This may partly answer my question about why people don't notice or study the concepts docs. Maybe we're too used to clicking on search results and getting fast answers to small questions; we're not used to methodically reading introductory material and building a foundation of understanding, at least not to the extent required by Cocoa. When I was a NextStep programmer, it was clear to me that concepts docs came first, then reference docs. I don't know if NeXT did all that much to reinforce that mindset. It may just have been because I hadn't been spoiled on Google yet. (Not to knock Google. Searching for blah site:developer.apple.com is often -- not always, but often -- *much* more likely to return relevant hits than searching with the Xcode documentation window. I assume this is because Google has much more data and better algorithms to be able to assign relevancy to web pages. On the other hand, Google can't do a Contains search.) --Andy ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
Re: The challenge for Cocoa's on-line documentation
Wikis like CocoaDev can be nice for filling these gaps. I find it helpful to see not only the articles, which are usually practical, but also visitor comments. For example, someone can easily add a statement to a 4-year-old page, pointing out a new approach that works better. Or, a debate can begin, where people show multiple solutions or point out problems they've had. Kevin G. On May 16, 2008, at 5:05 PM, Erik Buck wrote: [Re-post from http://www.cocoabuilder.com/archive/message/cocoa/2007/8/20/188026 ] That was well worth reposting. This may partly answer my question about why people don't notice or study the concepts docs. Maybe we're too used to clicking on search results and getting fast answers to small questions; we're not used to methodically reading introductory material and building a foundation of understanding, at least not to the extent required by Cocoa. When I was a NextStep programmer, it was clear to me that concepts docs came first, then reference docs. I don't know if NeXT did all that much to reinforce that mindset. It may just have been because I hadn't been spoiled on Google yet. (Not to knock Google. Searching for blah site:developer.apple.com is often -- not always, but often -- *much* more likely to return relevant hits than searching with the Xcode documentation window. I assume this is because Google has much more data and better algorithms to be able to assign relevancy to web pages. On the other hand, Google can't do a Contains search.) --Andy ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
Re: The challenge for Cocoa's on-line documentation
Very good post, Erik. Here's what I feel now about this issue. I too am having difficulties to learn Cocoa. The problem might be that I'm new to both Cocoa and Objective C. I've seen some tutorials that try to teach them at the same time. I'm afraid they might be a little too shallow, exploring some specific details while failing to explaing the background. Without having learned Objective C, I don't feel confident to have a go at Cocoa. On the other hand, when I see Objective C tutorials, they seem to be targeted to the begining programmer. They'll explain the OO theory, and what a function is, etc. So, while I do appreciate learing the quirks of Objective C, having to read all that theory that I learned 10+ years ago turns out to make the text very boring and uninteresting. In that sense, I think a mere From Java to Objective C in 10 days book would be the quickest way to get there, even though I don't usually recommend or have this kind of book. Having learned Objective C, understanding Cocoa seems a tad less of a challenge. But only after that would I turn to Apple's concepts documentation on Cocoa. -- Gustavo Eulalio [EMAIL PROTECTED] On Fri, May 16, 2008 at 6:05 PM, Erik Buck [EMAIL PROTECTED] wrote: The potential audience for a computer programming documentation can range from beginner's who don't know what a compiler is to people who are experts themselves and just want a quick reference. Beginners are frustrated when prerequisite knowledge is assumed, and experts are frustrated when they have to search through redundant introductory material in order to find the nugget they seek. In the middle of that spectrum are programmers who are expert users of other frameworks. These programmers often want a quick translation guide. I would do such and such this way using that framework; how can I do it with Cocoa? Sometimes we even see programmers in the various forums complain that Cocoa works differently than some other framework. I don't know how to respond to that other than say, Yup, Cocoa works differently than that. Authors have an additional challenge when writing on-line documentation. With a printed book, it is usually safe to assume that readers start at the beginning or will at least flip back a few chapters if they get lost. Readers come to on-line documentation in seemingly random order. A single search might identify twenty pages of information at various points along the spectrum from beginner to expert. The odds are _not_ in the author's favor that readers will understand the prerequisites and context needed to understand a page found at random. Once again, a newbie who chances upon expert level documentation will be frustrated and report that the documentation isn't helpful. An expert who finds extremely introductory information will complain that the documentation is too bulky and it's too hard to find information. Cocoa presents yet another challenge. In most respects, Cocoa is not an al-la-cart framework. There are key design patterns, repeated idioms, optional conventions, and most importantly some essential conventions. No matter how much experience a programmer may have, if the programmer fails to adhere to essential conventions (like Cocoa memory management conventions), they will not succeed with Cocoa. It is common that an experienced programmer will get started by searching Apple's on-line documentation and miss critical details. A symptom of this phenomenon is a mailing list post claiming that NSMutableDictionary is broken because the class is following essential conventions that the programmer isn't. As an aside, this phenomenon is not unique to Cocoa. I recall similar postings regarding Microsoft's IUnknow COM interface in COM mailing lists. I remember postings to device driver mailing lists indicating that the poster had some very strange conceptions about what a device driver is. It seems common to me that programmers who are completely unfamiliar with graphics programming will get upset about one detail or another of a graphics API particularly when mathematics are required. My point is only that Apple's Cocoa documentation and mailing lists are not the only ones to suffer from criticisms in the various categories I have described. Back to the subject: there is yet another problem: I just want to do such and such? Why is it so hard? These questions often prompt the why do you want to do that? or don't fight the frameworks or what are you really trying to do? responses. I don't think any kind of documentation can avoid these questions or answer them. Sometimes the question is along the lines of I just want to build a launch vehicle that will put my neighbor's dog into space. It's not as if I want the dog to survive. why is it so hard? What kind of book can really answer that kind of question? The bottom line is that Apple's
