Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Steve Weller <email@hidden>
- Date: Sun, 10 Jul 2005 16:07:33 -0700
At 12:32 AM -0400 7/10/05, Erik Buck wrote:
Picking on the lauded MSDN and Win 32, consider the following:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/windowsuserinterface/windowing/windows/windowfeatures.asp
How is Win32 BringWindowToTop() more intuitive than Cocoa
-orderFront: especially on an MSDN page about window ORDER ? The
MSDN page that describes Window z-order (itself a term unfamiliar to
noobs) has no direct mention of how to "hide" a window. It only
directly describes closing a window. It describes the
IsWindowVisible() function but there is no SetWindowVisible()
function or HideWindow() function !
A common thread I see through this discussion is that the
documentation mixes and confuses "what is achieved" with "how it is
done". A big improvement to the docs would be to clearly describe
everything separately in those terms:
-orderOut
What it does: Hides the window from view
How it does it: Changes the position of the NSWindow object reference
in the array of window.... (blah blah)
In other words, "what it does" is an external description, looking
in. "How it does it" is an internal description, looking out.
Separating the information in this way would free up both types of
descriptions by letting them use different language to describe the
same thing, so avoiding crimping either and making searches
consistent for either type of query. Think in terms of separation of
implementation from interface.
--
How much art could an artichoke choke if an artichoke could choke art?
_______________________________________________
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