Re: Documentation frustrations
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