Proposal Smart Help

From Audacity Wiki
Revision as of 09:15, 1 September 2008 by James (talk | contribs) (Answers...)
Jump to: navigation, search


One of the main features of Smart Help is to provide detailed context sensitive information on each configurable parameter in the preferences panel.

This will allow us to use very short descriptions in the preferences panel, e.g. just a tick box with the word 'Overdub' beside it. Experienced users will already know what this does. Inexperienced users or users who have forgotten what the parameters in a particular parameter group do can click on the title for a group to get a description for each parameter in the group.



Current design difficulties:

In my prototype the help panel is a strip on the right side of the preferences dialog that is there all the time. That makes the preferences dialog rather wide. Current thinking is that on the interface panel in show/hide we add a tick box 'help on preferences'. It's ticked by default. When unticked the help vanishes and the dialog goes back to its normal size. Unlike most items its effect is immediate, i.e don't wait for OK/Cancel. Will we need the option of the help appearing in a separate window rather than making preferences wider?


I rather doubt the "widened Preferences" idea will work - what about the 800 x 600 screen size? The ways I've seen this done are:

  1. An additional help window (either disappears when preferences are exited or not)
  2. Same idea, but integrated with the inbuilt help, so there is no need to write extra text
  3. A pop up window or tooltip just for the item in question as per LRN's custom exporter (Leland would have to advise on the accessibility implications here)

Personally I like the third idea best, and the first least. The third one increases the chance of everyone seeing "near-essential" text like "uncheck when recording "stereo mix"" and could make it easier to omit it from the actual wording.


I'm not planning a per-item tooltip. It's going to be per wxStaticBox. I've experimented with this and found that this allows groups of related parameters to be explained better and in their proper context. Tooltips are OK for a small amount of text, e.g. telling you what a graphic button actually is. When you need a lot of text, and the whole point of this feature is to allow us to have as much descriptive text as we need, then you need a window that doesn't keep jumping around on the screen as you 'probe' one item after another.


I've re-read the original suggestion about the two way interaction between the HTML window and the Prefs. panel, and the implication there seems that the window actually has all the expanded text for the preferences, and scrolls? But I can't visualise that so easily with the clip-on to Preferences idea - was that just containing the text for the static box, or for the whole Preferences help text?

Clearly there are cases where grouping text by static box makes sense (e.g. FFT size). Talking together about two related radio buttons out of a number of elements in a box seems good too. But have you done a mock up of say "When importing audio files" (note the checkbox there is pretty unrelated to the radio buttons). And what about "Behaviors" on the Interface tab? I really can't visualise those nine elements as a static clip-on to the Preferences, if that's what it is.

Rightly or wrongly, my gut feeling at the moment is that the grouped text you're suggesting is going to be too nearly a duplication of the reference section of the manual; if so it might make more sense to wait if necessary and link the Preferences to inbuilt help, not to a custom and separate preferences help. I think having the manual built in is more important, and a subject of criticism in apps. when it isn't. Or are there technical obstacles to highlighting text inside the Help browser?

James: The grouped text is the manual text for just those options. We shouldn't need to write extra text. We just need to make sure we've explained each preference clearly in the manual. The point is that even with a manual people don't read it and/or can't find their way around easily. Being able to click on a static box and find out "what the stuff in it for" is what this is about. The prototype has the help in a html window, which is a narrow scroller on the right. With a decent sized screen I find that works best for me, though it is as easy to use the built-in help browser instead.


I also think there is a case for an "intermediate" level of quick help, probably per item, which (in other apps) might go directly in the interface. For this, a tooltip/pop up is appropriate, though I understand there are issues such as tooltips for check boxes. I see this "intermediate" help as additional to a help button per Preferences tab or per static box which goes to a reference section. I think per-item help will assist newbies more, if they don't actually click our help icon for fear of information overload/having to wade though a whole help section. This is a real problem in some apps, and they may assume ours is the same. Maybe these in-situ hints could be turned off by a preference.

James: I have three triggers for updating the help scroller. Clicking on a static box (not on a control), changing any parameter, changing to a new tab. These would all be active on a fresh install so the new-user would see the help. I think this sufficiently reduces the risk of a user not discovering that there is useful help? Because it is in a fixed place it is easier for the possibly overloaded noob to take it or leave it. A fundamental problem with the quick-help as tooltip is that potentially it needs to be the full length of the manual help for that item, or it might not say enough. Even the full strings we've been suggesting for preference items as stopgap are long and still a bit cryptic. A new user might come to rely on the tooltips and get stuck when they hit a difficult one which we've had to keep short, whereas with the panel-based help we're easing them gently into actually reading the manual - and making sure our manual is organised so that it is right for dipping into.