• 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: Andre <email@hidden>
  • Date: Sun, 10 Jul 2005 14:26:06 -0700

Please, I have said that this is not helpful. Keep it relevant to actual issues relating to the documentation. Discussion of the production process, when you don't know what the production process is, is not helpful. Tell us where you would like to go, not how you think we should get there.

Ok, here's another thing that is annoying.
I'm in interface builder, and I am learning bindings, so I open the inspector to inspect one of your Coredata/Bindings examples, so I mouse over each binding such as contentValues and the tooltip says "specifies the content values of the bound object" well, not to be offensive, but, naw really?? Thats a totally useless tooltip.


So now I wanna find the difference between content and contentValues bindings for NSTableColumn, so I click the purple question mark on the inspector to be greeted by "An Apple Human Interface Guidelines document is not available for the current selection." Thanks a lot....

Why does Xcode help and Interface Builder help open two separate help systems?? Kinda redundant isn't it?

Another example, I want to find more info relating to @unionOfSets that I found in one of the bindings, so I search in interface builder help for @unionOfSets... nothing. Ok, I search in XCode documentation, I get two results, with the place not being highlighted (in the text it should also jump there) where the text was found, so I do another search (cmd+F), and find it... here is the explanation for the key @unionOfSets : "The @unionOfSets array operator" ... gee thanks! That explains everything!

How about more info such as the context of its use, what unions of what sets, what are appropriate values in those sets... etc etc... it goes on and on like this all over the place... everything is disjointed... relations that should exist don't, and explanations that should explain don't.

Here is the ideal solution, I'm in the bindings inspector, I mouse over each binding, a tool tip gives a real explanation, not just the binding name plus spaces and verbs. In the tool tip there are links to more areas of documentation. Second, if I click on a binding to see more, the other binding I was looking at collapses! How can I compare them then, take screenshots?? So I inspect the binding, and I see an @unionOfSets key, so I wanna find more info, I should be able to click @unionOfSets and like in Mail.app address, a pop-down menu lets me choose some options such as docs, examples, methods, etc that I can continue my search... this is what I mean about putting it in a database where everything is interrelated, then searching can be automatic all over the place...

Lastly, I know you don't want to hear things about the production process, but that just may be the problem.
Are the people that write the docs also the same engineers that work on the code?? If so, no wonder.
They are probably so overworked already they don't have time to write appropriate explanations, and the second thing
is that most devs already know how everything works, so when they write the docs, its hard for them to do
it from the perspective someone who knows little... again, please forgive me for assuming, but thats just what I see...
Its not in the job description for software engineers to write documentation is it??
Its just my feeling... again, I don't know the production process, but the results look like what I have seen elsewhere...


Thanks for reading this...

Andre
_______________________________________________
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: Scott Anguish <email@hidden>
    • Re: Documentation frustrations
      • From: mmalcolm crawford <email@hidden>
References: 
 >Re: Documentation frustrations (From: Raffael Cavallaro <email@hidden>)
 >Re: Documentation frustrations (From: mmalcolm crawford <email@hidden>)

  • Prev by Date: Re: Best time to add observers for managed object?
  • Next by Date: Re: Documentation frustrations
  • Previous by thread: Re: Documentation frustrations
  • Next by thread: Re: Documentation frustrations
  • Index(es):
    • Date
    • Thread