• Open Menu Close Menu
  • Apple
  • Shopping Bag
  • Apple
  • Mac
  • iPad
  • iPhone
  • Watch
  • TV
  • Music
  • Support
  • Search apple.com
  • Shopping Bag

Lists

Open Menu Close Menu
  • Terms and Conditions
  • Lists hosted on this site
  • Email the Postmaster
  • Tips for posting to public mailing lists
Re: Documentation frustrations
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Documentation frustrations


  • Subject: Re: Documentation frustrations
  • From: Carlos Salinas <email@hidden>
  • Date: Sat, 9 Jul 2005 00:09:22 -0700

I can see where there is a lot of information about obj-c, and I can see where it'd be hard to organize It' not just what is written, but the way it's organized on the site.


If you have suggestions for organisation that you think would make things easier, please let me know.

Back in the day (NeXTSTEP, a decade ago now) we had a simple application that you could use to search through all the documentation, all the example code, all the header files, and other folders (such as your source code). The hits were presented in a simple, clean list - no gobs of white space between rows or organizing goop. In the same window below that list was a text field. Selecting an item in the list displayed the matching document in the text field below. Simple. Dumb. Stupid. Yet it worked well. One could type in setIsVisible: and find every single documentation reference, the header declaration, every example code reference, and every use in your own code and then quickly and easily browse through all those hits to get a better understanding of how that method worked. Now we have gobs and gobs of complexity and nothing I've found matches the simplicity or utility of that older solution.


Something I expected would be in one section is instead posted in another. It's just hard to find things in most cases, and some pages are utterly useless they have 2 paragraphs of 3-4 sentences that really don't tell you anything, even in some of the docs for specific objects, you look at a method, and look at it's description, and your like "WTF does that mean?". It's just bad.

When you find cases like this, please file bug reports.

The QuickTime documentation is a good example of documentation fragmentation. (The function documentation itself is great, better than Cocoa because each parameter is described, the function itself is discussed and the return value is mentioned.) The QuickTime documentation is fragmented because each function, type and constant are presented on separate web pages. That makes it harder to grok the entire API. The thing about documentation is the knowledge that is picked up serendipitously while looking for something else. When several functions are on a single page, I might start looking for function XYZ and end up browsing across the much more useful function ABC. Fragmenting the documentation restricts those discoveries.


A similar thing happened to the Cocoa documentation. Originally the classes had large and extensive descriptions. You might start looking for one method and end up learning a lot more about the class because the description was on the same page. But now the description has been broken out into a separate page and that makes it harder to learn about the class.
_______________________________________________
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
  • Follow-Ups:
    • Re: Documentation frustrations
      • From: Tom Blenko <email@hidden>
    • Re: Documentation frustrations
      • From: Andy Lee <email@hidden>
References: 
 >Re: Documentation frustrations (From: Raffael Cavallaro <email@hidden>)
 >Re: Documentation frustrations (From: mmalcolm crawford <email@hidden>)
 >Re: Documentation frustrations (From: Raffael Cavallaro <email@hidden>)
 >Re: Documentation frustrations (From: mmalcolm crawford <email@hidden>)
 >Re: Documentation frustrations (From: Raffael Cavallaro <email@hidden>)
 >Re: Documentation frustrations (From: mmalcolm crawford <email@hidden>)
 >Re: Documentation frustrations (From: James Andrews <email@hidden>)
 >Re: Documentation frustrations (From: Guy English <email@hidden>)
 >Re: Documentation frustrations (From: James Andrews <email@hidden>)
 >Re: Documentation frustrations (From: mmalcolm crawford <email@hidden>)

  • Prev by Date: Re: Documentation frustrations
  • Next by Date: Re: newbie: Why would a NSSecureTextField show a cursor but a NSTextField not?
  • Previous by thread: Re: Documentation frustrations
  • Next by thread: Re: Documentation frustrations
  • Index(es):
    • Date
    • Thread