why are there zero examples in the cocoa docs?!

  • Hi,

    or in other words:
    why does the documentation suck so much (for beginners)? :-)
    am i researching the wrong place?

    when looking at for example the php documentation, every method has at
    least a nice syntax sample...
    when reading the cocoa doc, i have something like this:
    addChapters
    Adds chapters to the receiver using the information specified in the
    chapters array.

    - (void)addChapters:(NSArray *)chapters withAttributes:(NSDictionary
    *)attributes error:(NSError **)errorPtr

    Discussion
    Each array element is an NSDictionary containing key-value pairs.
    Currently two keys are defined for this dictionary,
    QTMovieChapterNameand QTMovieChapterStartTime. The value for the
    QTMovieChapterName key is an NSString object that is the chapter name.
    The value for the QTMovieChapterStartTime key is an NSValue object
    that wraps a QTTime structure that indicates the start time of the
    chapter. The receiving QTMovie object must be editable or an exception
    will be raised.

    The attributes dictionary specifies additional attributes for the
    chapters. Currently only one key is recognized for this dictionary,
    QTMovieChapterTargetTrackAttribute, which specifies the QTTrack in the
    receiver that is the target of the chapters; if none is specified,
    this method uses first video track in movie. If no video track is in
    the movie, this method uses the first audio track in the movie. If no
    audio track is in the movie, this method uses the first track in the
    movie. If an error occurs and errorPtr is non-NULL, then an NSError
    object is returned in that location.

    yeah..... cool.... what?

    so probably i have to call something like:

    [myMovie addChapters:myChapterArray]

    but i have really no idea how that chapterarray should look like :-/

    looking forward for the "initial hint" that will hopefully light the
    spark :-)

    best,

    --Joeles
  • On Jan 19, 2008 2:47 PM, Joeles Baker <joelesbaker...> wrote:
    > Hi,
    >
    > or in other words:
    > why does the documentation suck so much (for beginners)? :-)
    > am i researching the wrong place?

    It's not so much that the documentation sucks, it's probably more that
    you haven't yet wrapped your head around how Cocoa operates.

    I had the exact same reaction that you had when I started.  I
    literally printed out every guide I could (Core Data, Key-Value
    Coding, Document-based Applications...) and read them over and over
    again.  I found the lack of examples attached to method descriptions
    frustrating at first.  But eventually I came to the realization that
    MSDN-style documentation is unnecessary for most of Cocoa.  Almost
    everything is implicit, and if not, it's intuitive.  You just need to
    understand high-level concepts (delegates, model-view-controller,
    etc.) to immediately intuit the purpose of most methods.  More verbose
    documentation (and guides) are usually provided for those features
    that aren't covered by this mental model.

    I guess it's a roundabout way of saying that learning Cocoa isn't
    about looking up contracts in the manual, it's about hammering at,
    tearing down, and rebuilding your mental model until it resembles the
    actual model of how Cocoa works.  That's not to say that the
    documentation couldn't stand to be improved; I personally feel that
    there are a lot of portions of frameworks that are missing guides,
    such as some of the filesystem stuff in Core Foundation.  But Cocoa
    isn't meant to be written the way PHP, Win32, and even Carbon are, so
    it takes a little getting used to how the documentation is written (or
    not) as a result.

    --Kyle Sluder

    P.S.: I wouldn't look to the PHP documentation as an example of
    shining brilliance.  It is frequently out of sync with the actual
    codebase, retains descriptions of functionality deprecated in previous
    releases, provides unnecessary implementation details (effectively
    turning them into guarantees, when they have no business in the public
    interface) and is plagued with people incorrectly (re-)implementing
    functionality in the comments section.
  • On 19 Jan 08, at 11:47, Joeles Baker wrote:
    > or in other words:
    > why does the documentation suck so much (for beginners)? :-)
    <snip>
    > yeah..... cool.... what?
    >
    > so probably i have to call something like:
    >
    > [myMovie addChapters:myChapterArray]
    >
    > but i have really no idea how that chapterarray should look like :-/
    >
    > looking forward for the "initial hint" that will hopefully light the
    > spark :-)

    "Each array element is an NSDictionary containing key-value pairs.
    Currently two keys are defined for this dictionary,
    QTMovieChapterNameand QTMovieChapterStartTime. The value for the
    QTMovieChapterName key is an NSString object that is the chapter name.
    The value for the QTMovieChapterStartTime key is an NSValue object
    that wraps a QTTime structure that indicates the start time of the
    chapter."

    Everything you need to know is right there. If some of the terms
    aren't familiar, look them up - NSDictionary, NSString, and NSValue
    are all basic Cocoa concepts which you _need_ to be familiar with, and
    QTTime is something you'll need to know about if you're doing anything
    with Quicktime.
  • > why does the documentation suck so much (for beginners)? :-)

      A counter-question: Why do beginners always assume the trouble
    they're having with documentation is automatically the documentation's
    fault?

    > am i researching the wrong place?

      Probably. There is a *lot* of documentation and, contrary to your
    opinion, many say that this is the best documentation they've seen for
    a platform / language / API. I'd tend to agree.

      No matter how well-written the technical specifications are for the
    design of every part of a given car, you're not going to be able to
    build a car just like it from scratch just by reading the individual
    specs of each of its parts. You've got to read the blueprint, the
    materials list, an overview of the sub-assemblies, etc.

      In short, you're going about this ass-backwards.

      The best place is the beginning:

    Getting Started with Cocoa
    http://developer.apple.com/referencelibrary/GettingStarted/GS_Cocoa/index.h
    tml


    The Objective-C 2.0 Programming Language
    http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Introd
    uction/chapter_1_section_1.html


    Cocoa Fundamentals
    http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaFundamentals
    /Introduction/chapter_1_section_1.html


    Cocoa Application Tutorial
    http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/01In
    troduction/chapter_1_section_1.html


      Take your time. I was a complete newbie to Cocoa a few years back
    and, though it was difficult and took awhile to pick up Objective-C
    and Cocoa's architecture, I found the documentation (and the books
    recommended on the Fundamentals page) invaluable and an excellent
    resource that's constantly improved.

      *There is no substitute for doing your research.*

    > - (void)addChapters:(NSArray *)chapters withAttributes:(NSDictionary
    > *)attributes error:(NSError **)errorPtr
    > so probably i have to call something like:
    >
    > [myMovie addChapters:myChapterArray]

      No, this is where reading the introductory material above
    (particularly the Objective-C guide) comes in handy (as well as a good
    working knowledge of C++, of which Objective-C is a superset). You
    have to call:

    [myMovie addChapters:myChaptersArray
    withAttributes:myAttributesDictionary error:&someErrorPointer];

      You can't simply ignore the method signature. It's not the API
    reference's fault that you do not know Objective-C syntax. It's also
    not the API reference's job to teach it to you. That's the guide
    above's job. It's *your* job to read it.

    > looking forward for the "initial hint" that will hopefully light the
    > spark :-)

      It sounds superior and smug, I know (and it is somewhat because
    it's a rather obvious concept), but that's really the best advice
    you're going to get: Read and re-read the introductory material until
    you understand it because you won't get anywhere without mastering the
    basics.

      If you get lost and have questions on what you're reading, post
    back to the list for clarification.

    --
    I.S.
  • One small comment on the comments by I. Savant, who is generally right
    on target:  Objective-C is a superset of C, not C++, as I'm sure he
    knows.  Thought I should mentioned it, lest the originator of the
    original question (rant?) thinks he needs to start learning C++ (God
    forbid).

    Boyd

    On Jan 19, 2008, at 12:36 PM, I. Savant wrote:

    >> why does the documentation suck so much (for beginners)? :-)
    >
    > A counter-question: Why do beginners always assume the trouble
    > they're having with documentation is automatically the
    > documentation's fault?
    >
    >> am i researching the wrong place?
    >
    > Probably. There is a *lot* of documentation and, contrary to your
    > opinion, many say that this is the best documentation they've seen
    > for a platform / language / API. I'd tend to agree.
    >
    > No matter how well-written the technical specifications are for the
    > design of every part of a given car, you're not going to be able to
    > build a car just like it from scratch just by reading the individual
    > specs of each of its parts. You've got to read the blueprint, the
    > materials list, an overview of the sub-assemblies, etc.
    >
    > In short, you're going about this ass-backwards.
    >
    > The best place is the beginning:
    >
    > Getting Started with Cocoa
    > http://developer.apple.com/referencelibrary/GettingStarted/GS_Cocoa/index.h
    tml

    >
    > The Objective-C 2.0 Programming Language
    > http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Introd
    uction/chapter_1_section_1.html

    >
    > Cocoa Fundamentals
    > http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaFundamentals
    /Introduction/chapter_1_section_1.html

    >
    > Cocoa Application Tutorial
    > http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/01In
    troduction/chapter_1_section_1.html

    >
    > Take your time. I was a complete newbie to Cocoa a few years back
    > and, though it was difficult and took awhile to pick up Objective-C
    > and Cocoa's architecture, I found the documentation (and the books
    > recommended on the Fundamentals page) invaluable and an excellent
    > resource that's constantly improved.
    >
    > *There is no substitute for doing your research.*
    >
    >> - (void)addChapters:(NSArray *)chapters withAttributes:
    >> (NSDictionary *)attributes error:(NSError **)errorPtr
    >> so probably i have to call something like:
    >>
    >> [myMovie addChapters:myChapterArray]
    >
    > No, this is where reading the introductory material above
    > (particularly the Objective-C guide) comes in handy (as well as a
    > good working knowledge of C++, of which Objective-C is a superset).
    > You have to call:
    >
    > [myMovie addChapters:myChaptersArray
    > withAttributes:myAttributesDictionary error:&someErrorPointer];
    >
    > You can't simply ignore the method signature. It's not the API
    > reference's fault that you do not know Objective-C syntax. It's also
    > not the API reference's job to teach it to you. That's the guide
    > above's job. It's *your* job to read it.
    >
    >> looking forward for the "initial hint" that will hopefully light
    >> the spark :-)
    >
    > It sounds superior and smug, I know (and it is somewhat because
    > it's a rather obvious concept), but that's really the best advice
    > you're going to get: Read and re-read the introductory material
    > until you understand it because you won't get anywhere without
    > mastering the basics.
    >
    > If you get lost and have questions on what you're reading, post
    > back to the list for clarification.
    >
    > --
    > I.S.
    >
  • Hi I. Savant, Andrew, Kyle,

    just wanted to say thank you for all your comments.
    I hope they'll help me on my way.

    :-)

    best

    --Joeles
  • On Jan 19, 2008 7:47 PM, Joeles Baker <joelesbaker...> wrote:

    > why does the documentation suck so much (for beginners)? :-)
    ...
    > "Each array element is an NSDictionary containing key-value pairs."
    ...
    > but i have really no idea how that chapterarray should look like :-/
    ...
    > looking forward for the "initial hint" that will hopefully light the
    > spark :-)

    My initial hint would be: if you approach mailing lists with humility
    rather than casting aspersions, you're less likely to be told to RTFM.

    My follow-up hint would be: if you don't know what an NSDictionary is, RTFM!

    Hamish

    P.S. Please read this email tongue-in-cheek; if others hadn't already
    made such constructive replies, I'd have tried to be more helpful :)
  • Sent from my iPod

    On Jan 19, 2008, at 3:16 PM, "Hamish Allan" <hamish...> wrote:

    > On Jan 19, 2008 7:47 PM, Joeles Baker <joelesbaker...>
    > wrote:
    >
    >> why does the documentation suck so much (for beginners)? :-)
    > ...
    >> "Each array element is an NSDictionary containing key-value pairs."
    > ...
    >> but i have really no idea how that chapterarray should look like :-/
    > ...
    >> looking forward for the "initial hint" that will hopefully light the
    >> spark :-)
    >
    > My initial hint would be: if you approach mailing lists with humility
    > rather than casting aspersions, you're less likely to be told to RTFM.
    >
    > My follow-up hint would be: if you don't know what an NSDictionary
    > is, RTFM!
    >
    > Hamish
    >
    > P.S. Please read this email tongue-in-cheek; if others hadn't already
    > made such constructive replies, I'd have tried to be more helpful :)
  • On Jan 19, 2008, at 5:59 PM, Boyd Collier wrote:

    > Objective-C is a superset of C, not C++, as I'm sure he knows.
    > Thought I should mentioned it, lest the originator of the original
    > question (rant?) thinks he needs to start learning C++ (God forbid).

      Of course you're right. I always say "C++" for some reason. :-)

    --
    I.S.
  • On Jan 19, 2008, at 2:47 PM, Joeles Baker wrote:

    > Hi,
    >
    > or in other words:
    > why does the documentation suck so much (for beginners)? :-)
    > am i researching the wrong place?

    You've had a lot of other replies.. but as someone involved in Tech
    Pubs at Apple, I can give one more hint.

    We don't typically put source code in the reference at all.  It goes
    in the accompanying conceptual doc.

    References tells you what it does.  Conceptual tells you how to do it.

    If you can't find it, submit feedback.
  • Op 20-jan-2008, om 8:15 heeft Scott Anguish het volgende geschreven:

    >
    > On Jan 19, 2008, at 2:47 PM, Joeles Baker wrote:
    >
    >> Hi,
    >>
    >> or in other words:
    >> why does the documentation suck so much (for beginners)? :-)
    >> am i researching the wrong place?
    >
    > You've had a lot of other replies.. but as someone involved in Tech
    > Pubs at Apple, I can give one more hint.
    >
    > We don't typically put source code in the reference at all.  It
    > goes in the accompanying conceptual doc.

    Then it would be nice to have in the reference references ( link ) to
    the accompanying conceptual doc.

    >
    > References tells you what it does.  Conceptual tells you how to do it.
    >
    > If you can't find it, submit feedback.
    >
  • On Jan 20, 2008, at 2:20 AM, René v Amerongen wrote:

    > Then it would be nice to have in the reference references ( link )
    > to the accompanying conceptual doc.
    >
    They typically do, at the top of each reference -- see "Companion
    guides" in, for example, <http://developer.apple.com/documentation/Cocoa/Reference/Foundation/Classes
    /NSString_Class/Reference/NSString.html
    >.

    If there's no companion guide listed, it means there's either no
    conceptual material or the link hasn't been established yet.  In such
    a case, it's probably worth doing a full-text search for the class/
    symbol you're interested in and seeing if it is described in a
    conceptual document.  If it is not, then file an enhancement request
    for it to be written; if it is, then file a bug stating that the link
    is missing.

    mmalc
  • Re: why are there zero examples in the cocoa docs?!
    As someone who is just getting into the depths (toes first) of Cocoa I
    appreciate the nature of
    Joeles remarks with regards to the apparent disconnect between
    concrete examples and
    the reference material. I think the main problem is that Cocoa
    demonstrates a much
    higher degree of abstraction than is found in say .NET. Or perhaps it
    is that in .NET less
    is made of the abstraction and more is made of the concrete. But I
    think the stern intellectual
    presentation of Cocoa's abstractions is part of its appeal. The .NET
    environment is definitely more
    discoverable than Cocoa/Xcode - you can get things to work without
    having to understand them in great depth.
    Not so, I think, with our illustrious Cocoa - understanding has to
    come first. This makes learning
    Cocoa truly challenging, but ultimately worthwhile. And, to me, at
    least there is real
    mental pleasure in getting my mind to comprehend the nature of Cocoa's
    structures.
    Jonathan
    > FROM : mmalc crawford
    > DATE : Sun Jan 20 12:11:00 2008
    >
    > On Jan 20, 2008, at 2:20 AM, Ren� v Amerongen wrote:
    >
    >> Then it would be nice to have in the reference references ( link )
    >> to the accompanying conceptual doc.
    >>
    >
    > They typically do, at the top of each reference -- see "Companion
    > guides" in, for example, <http://developer.apple.com/documentation/Cocoa/Reference/Foundation/Classes
    /NSString_Class/Reference/NSString.html
    > >.
    >
    > If there's no companion guide listed, it means there's either no
    > conceptual material or the link hasn't been established yet.  In such
    > a case, it's probably worth doing a full-text search for the class/
    > symbol you're interested in and seeing if it is described in a
    > conceptual document.  If it is not, then file an enhancement request
    > for it to be written; if it is, then file a bug stating that the link
    > is missing.
    >
    > mmalc
  • On Jan 19, 2008, at 11:47 AM, Joeles Baker wrote:

    > why does the documentation suck so much (for beginners)? :-)
    > am i researching the wrong place?
    > when looking at for example the php documentation, every method has
    > at least a nice syntax sample...
    > when reading the cocoa doc, i have something like this:
    > addChapters
    > Adds chapters to the receiver using the information specified in the
    > chapters array.
    > - (void)addChapters:(NSArray *)chapters withAttributes:(NSDictionary
    > *)attributes error:(NSError **)errorPtr
    >
    Another aspect to this is that QTKit is not a "core" Cocoa framework.
    There are likely to be fewer examples of *basic* techniques than in,
    say, Foundation or AppKit.

    The subject line notwithstanding, there *are* many examples in the
    documentation -- even in the API reference.  One of the most extreme
    examples perhaps is given in NSMutableArray:
    <http://developer.apple.com/documentation/Cocoa/Reference/Foundation/Classes
    /NSMutableArray_Class/Reference/Reference.html#//apple_ref/occ/instm/NSMuta
    bleArray/insertObjects:atIndexes:
    >

    mmalc
  • I'd like the tutorial documents to be available as hard copy --
    nothing fancy, just the pdfs stuck together in a paperback book, and
    not the reference documentation, searching is fine for that. Of course
    being able to search the tutorial documentation is extremely valuable
    too, but many documents I want to read start to finish, which I find
    much more convenient in paper form. I always end up with a pile of dog
    eared two-up A4 pages -- a bound copy would be much nicer.

    Tom
  • On Jan 20, 2008, at 6:02 PM, Tom Davies wrote:

    > I'd like the tutorial documents to be available as hard copy --

      That's come up on the list before. The documentation is updated
    often. Updates are released at least every few months, so it's not
    really feasible.

      Making a physical copy is easier for developers than it is for
    Apple's documentation team. You can download and print. They'd have to
    mass-produce the print and ship it at regular intervals or micromanage
    re-printing only updated docs and making sure you have the latest of
    each.

      Again, not very feasible. Hit print, use a stapler, and you're good
    to go. :-)

    --
    I.S.
  • There is!

    At the top of every reference doc there should be a section called
    "Companion Guides". That'll have those links for you.

    On Jan 20, 2008, at 5:20 AM, René v Amerongen wrote:

    >
    > Op 20-jan-2008, om 8:15 heeft Scott Anguish het volgende geschreven:
    >
    >>
    >> On Jan 19, 2008, at 2:47 PM, Joeles Baker wrote:
    >>
    >>> Hi,
    >>>
    >>> or in other words:
    >>> why does the documentation suck so much (for beginners)? :-)
    >>> am i researching the wrong place?
    >>
    >> You've had a lot of other replies.. but as someone involved in Tech
    >> Pubs at Apple, I can give one more hint.
    >>
    >> We don't typically put source code in the reference at all.  It
    >> goes in the accompanying conceptual doc.
    >
    > Then it would be nice to have in the reference references ( link )
    > to the accompanying conceptual doc.
  • On Jan 20, 2008, at 6:25 PM, I. Savant wrote:

    > On Jan 20, 2008, at 6:02 PM, Tom Davies wrote:
    >
    >> I'd like the tutorial documents to be available as hard copy --
    >
    > That's come up on the list before. The documentation is updated
    > often. Updates are released at least every few months, so it's not
    > really feasible.
    >
    > Making a physical copy is easier for developers than it is for
    > Apple's documentation team. You can download and print. They'd have
    > to mass-produce the print and ship it at regular intervals or
    > micromanage re-printing only updated docs and making sure you have
    > the latest of each.
    >
    > Again, not very feasible. Hit print, use a stapler, and you're good
    > to go. :-)

    failing that, any staples or other office supply store should be able
    to provide you a binding service.
  • On Jan 21, 2008, at 12:25 AM, I. Savant wrote:

    > Again, not very feasible. Hit print, use a stapler, and you're good
    > to go. :-)

    Or, like I do, use any one of a bunch of available programmes
    (preferably mine ;-) to create a "2-up" imposition to print, then take
    the printout to a copy shop and ask them to cut, assemble and bind it
    for you. Very easy and much cheaper than Apple could ever provide. And
    if the docs are fairly small you dont even need to cut. Just staple in
    the middle and fold. Voila: Documentation Booklet.

    Cheers,
    António
    http://sintraworks.com/

    -----------------------------------------------------------
    Some things have to be believed to be seen.

    --Ralph Hodgson
    -----------------------------------------------------------
previous month january 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