Re: Popup vs pull down menu item missing
Re: Popup vs pull down menu item missing
- Subject: Re: Popup vs pull down menu item missing
- From: Ian Joyner <email@hidden>
- Date: Wed, 3 Oct 2007 10:37:31 +1000
On 03/10/2007, at 3:40 AM, I. Savant wrote:
On Tue, 2 Oct 2007 10:18:29 +1000, Ian Joyner
<email@hidden>
said:
Thanks, but they are conceptual docs, not reference docs. What I'm
suggesting is that the reference docs, such as:
http://developer.apple.com/documentation/Cocoa/Reference/
ApplicationKit/ObjC_classic/index.html
should contain every bit of information, even in a boring terse form
(which it is anyway),
Okay, that tears it: mmalc and his group are fired. We're hiring
satirist Dave Barry to write our technical documentation from now on!
Accuracy and efficiency be damned - what this API reference needs is
PIZZAZ!!! ;-)
OK, I take the satire to be the exact opposite of what I'm saying ;-)
I don't want to make some blanket statement about the quality of the
documentation – it's pretty high, and writing documentation is
ultimately a no-win situation, so I'm not trying to sound like an
ingrate. The problem stems from the scale – there's a lot there and
sometimes it is fragmented, and you don't know there is something
else you should look for, like the semantics of pop-up and pull-down
menus are different, which led to some surprising behaviour.
Maybe, the problem comes from using the same class to handle popups
and pull downs, and thus the documentation people are left to make
the best of a perhaps bad situation. NSPopUpButtonCell certainly
contains a better "overview" than NSPopUpButton, but while Cell
points out there is a difference between popup and pulldown, does not
really precisely define it.
So, what I'm saying is precise definitions of everything should be in
the reference material, without having to go and read the conceptual
material, but if you can't understand the definition then go back to
the conceptual material. There is also a general debate about whether
reference material and conceptual material should be separated at
all. Bertrand Meyer tends to dislike that form of separation (as he
dislikes the traditional waterfall separation between analysts and
programmers), and so generally weaves conceptual and reference
material together into a highly readable document. Even so, he still
produces a reference book for Eiffel which contains a precise
definition of everything, that only a compiler writer might appreciate.
The nature of documentation is still evolving – I don't think we make
the best use of hypertext, but then again hypertext can be very
abused as seen on most Web sites where you feel you are going around
in circles. Fragmented chunks also makes it easy to perform some
searches, but difficult for others – that's why I often open up the
PDF, so I can search on terms through a whole document.
I think that setPullsDown: needs some modification. Maybe the problem
is in the line "This method does not change the contents of the menu;
it changes only the style of the menu.", because the content of the
menu was changed – I lost an item, which was gobbled up for the title
or something.
Anyway, I'm glad that you come out in defence of mmalc et al., but
don't assume that any comment on the documentation is just from
someone blowing hot air, or from someone who does not know what they
are talking about.
Ian
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden