The challenge for Cocoa's on-line documentation

  • 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 conceptual documentation is very good.  The only real problem is that people happen upon the conceptual documentation in random order or are too impatient to read it.  The information is in there.  Apple's reference documentation is also quite good, but it assumes that readers are familiar with the conceptual documentation or at least the critical concepts.  Apple has tried to satisfy the needs of both novices and experts and actually succeeds reasonably well in spite of the challenges.

      Because Cocoa is a cohesive system that is astoundingly consistent, a programmer who groks it can correctly guess class and method names, anticipate potential error cases, avoid unnecessary code, and benefit from legendary productivity.  A programmer who is missing one or more key concepts will find seeming barriers everywhere because Cocoa probably applies the concept ubiquitously.

      [Re-post from http://www.cocoabuilder.com/archive/message/cocoa/2007/8/20/188026]
  • On May 16, 2008, at 5:05 PM, Erik Buck wrote:

    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
  • 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
  • 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
    <guga.emc...>

    On Fri, May 16, 2008 at 6:05 PM, Erik Buck <erik.buck...> 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 conceptual documentation is very good.  The only real problem is that people happen upon the conceptual documentation in random order or are too impatient to read it.  The information is in there.  Apple's reference documentation is also quite good, but it assumes that readers are familiar with the conceptual documentation or at least the critical concepts.  Apple has tried to satisfy the needs of both novices and experts and actually succeeds reasonably well in spite of the challenges.
    >
    > Because Cocoa is a cohesive system that is astoundingly consistent, a programmer who groks it can correctly guess class and method names, anticipate potential error cases, avoid unnecessary code, and benefit from legendary productivity.  A programmer who is missing one or more key concepts will find seeming barriers everywhere because Cocoa probably applies the concept ubiquitously.
    >
    > [Re-post from http://www.cocoabuilder.com/archive/message/cocoa/2007/8/20/188026]
    > _______________________________________________
  • 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, <cocoa-dev-request...> wrote:

    > 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
  • 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/Cla
    sses/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!
  • 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
  • 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
  • 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.
previous month may 2008 next month
MTWTFSS
      1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31  
Go to today