Re: [lmi] LMI Help Proposal

[Greg Chicares]

On 2006-5-17 17:36 UTC, Ericksberg, Richard wrote:
> Tooltip
>     A little yellow box with text appearing over the control.
[which presents]
>     A brief [one or two word] explanation of "what" the control is
>    [e.g. Cut, Copy, Paste.]
[and which we plan to use only for]
>     High-level controls [navigational] such as main window toolbar
>     buttons that usually only have a picture.

In wxxrc terms, I believe the 'tooltip' tag is bound to this usage:
appropriately, it's always used only for a tooltip as defined. For
controls on a dialog, our current plan would be not to specify any
'tooltip' tag. I think that's a change from our original tentative
discussions with Vadim; is it final, or might we ever revisit it?

I read "one or two word" as descriptive, not prescriptive. I don't
think you'd object to the
  Print (Apple Color LW 12/660 PS)
tooltip ms excel shows me, and I assume you don't mean to require
changing lmi's current
  Print case to spreadsheet
tooltip. And if we ever want to enable tooltips on lmi's data-entry
dialog, I imagine the control labeled
  Experience-rating initial k factor
would call for no fewer words than that.

>   When is it available ?
>     Always, whether or not the control is.

I think lmi currently does that; if so, are you just ratifying it?
Or are you asserting that we ought always to do this, even if it
turns out that we don't today? I'm not sure which parts of this
text are normative prescriptions versus non-normative commentary.
My copy of ms 'internet explorer' doesn't work this way; I'm not
sure that's necessarily wrong.

> "What's This?" Help
>     A yellow box with text that appears in the vicinity of the control.
>   How is it invoked ?
>     1) By Clicking on the "?" button [i.e. activating the "? Cursor"]
>        and then clicking the control [not preferred - shifts user's
>        focus away from the control in question.]

Yet I don't think you're suggesting we suppress that, right? Is it
harmful to offer that for users who, however perverse it may seem,
prefer it to "What's This?"? I think you're saying that

 - in the problem domain, there are a couple ways of doing this,
   and you find good reason to prefer one and would like to make
   sure it's available; yet

 - in the solution domain, both ways are probably already available,
   and it might even require extra work to inhibit one;

and therefore solution-domain workers should be sure to implement
the second, preferred way, while also implementing the first if
it's essentially gratis, and certainly not inhibiting it if to
do so would be costly.

>     More detailed than a tooltip

Again, I read that as a suggestion, not a requirement. Look at lmi's
existing practice: wouldn't you agree that sometimes it appropriately
doesn't follow this suggestion, while elsewhere it less appropriately
follows it by introducing gratuitous differences that seem strained?

>     Always, whether or not the control is. If there is no useful
>     statement about a control, "What's This?" will evoke "Sorry Not
>     Available..." or something like that.

Do we ever need such a message at all? Is it better to provide help
text for every control just for uniformity? Does wx provide a suitable
default message already? Or does it already provide another behavior
that we might find suitable? What do, say, ms applications do? I'm
pretty sure they'll never say "Sorry"--they'll express facts instead
of emotions.

> F1 Help
>   How is it invoked ?
>     By pressing F1 for any control that has the focus.

What behavior should Ctrl-F1 or Shift-F1 have? Does wx by default
already do something appropriate for those combination keystrokes?

>     Launches HTML Help

Launches wxBestHelpController, as we've already discussed off this
mailing list. This shouldn't be read as changing that decision to
prescribe wxHtmlHelpController instead, which would move us away
from a native look and feel on the msw platform. Let me reiterate
that we will however get wxHtmlHelpController up and running first,
because I'm apprehensive that adding the 'chm' tools may prove more
difficult than we'd like--just because adding any tool we haven't
used before takes time and effort. Yet I imagine we'll want the
native look and feel before releasing this to end users.

> [if not already active.]

That sort of begs an obvious question, which I imagine we ought to
defer to initial testing, where we'll most likely conclude that
whatever wx already does is okay.

>     If no control has the focus, the user will be located at the top of
>     the HTML Help dialog.

Did you consider choosing a topic based on the active MDI child
('.ill' vs. '.cns') and consciously dismiss that idea?

>   Where is it appropriate ?
>     Lower-level controls [data entry, selection etc.] same as "What's
>     This?"
>   When is it available ?
>     Always, whether or not the control is.

Are the specified conditions for appropriateness and availability
consonant?

> HTML Help
> 
>   What is it ?
>     The Main Help Dialog.

You mean a separate application, not a dialog.

>   How is it invoked ?
>     1) By clicking the desired selection within the Help menu.

What selections would be added? For instance...

>     The standard Contents, Index and Search navigational facilities

...should these be separate menuitems? Does it matter much
whether they are or aren't?