Talk:Proposal Smart Help

From Audacity Wiki
Jump to: navigation, search

Policy on button tooltips

  • Gale 05Sep14:
James wrote "With the 'information' button mechanism, regular tooltips can and should be short. Normal style in modern applications is to be single-line. As an example, the 'home' button in Chrome browser has the phrase 'Open the home page' as its tooltip. We should do that too. We do not need to show shortcuts in the tooltip. Having a button IS a shortcut for mouse users. Keyboard users can learn the keyboard shortcut keys from the menus, or from the key-bindings preferences."
That seems to mean that toolbar button operations will be less accessible with the keyboard especially where there is no menu equivalent. Tools Toolbar is an example with no menu equivalent. Clearly there is a case that a button tooltip shows what the button does rather than what its shortcut is, though IE shows both. Are you suggesting an "i" button for every toolbar or only in a View > Customize Toolbars... central location? An "i" button per toolbar seems quite expensive in space usage.
  • James 05Sep14:
Every toolbar button SHOULD have a menu equivalent. In main Audacity I would be fine with adding menu items for the buttons in the tools toolbar (perhaps 'Edit->Set Tool->'), just as play-at-speed should be in the transport menu. In AU14 TrackPanel I have removed the need for the tools toolbar! For example there is no need for a zoom tool when you can pan and zoom using the ruler.
Background on accessibility generally: I have talked over with Leland about the route I want to go down and he, and his wife, think it is a lot better. It's to split Audacity into an audio only library and separately a GUI which connects to that. There would be a 'clutch' that you could engage, so that commands issued at the audio library level are reflected in the GUI. In theory someone else could write a completely different GUI using the same audio library. Rather than going through pain to make every GUI widget accessible, we give blind users text based access at the audio library level.
  • Gale 05Sep14: OK, though as I did not attend AU 14 you'll appreciate I can't visualise exactly what you mean. Do you mean you hear suggestions in screen readers about what commands you could use, but can't see them?
This is a lot more powerful and useful. One way to think about it is that everything involving the mouse is a problem for blind users. We are providing an interface to Audacity from before mouse (and graphics) are added. This approach also has major advantages for scripting.
With regards the keybindings of buttons, I am not removing the keybindings. I am only removing the tooltip route to discovery of them. So the toolbars are as accessible as before, it's just that the keybindings are less discoverable. Provided the tools are in the menus too, I don't see that as a problem. Using the i button one can argue that it's all become more accessible. It's fine to show the keybindings in the info panel where there is much more space than in a regular tooltip, and I would do that.
  • Gale 05Sep14: Yes, *if* toolbars have menu equivalents or an info panel it seems OK not to show bindings in tooltips. I don't think there absolutely has to be a menu equivalent for a tool in that case. The Edit menu has grown again for 2.0.6 and we chose to defer addressing that. However isn't the "AU" interface optional? If so, don't we still have the toolbar shortcuts discoverability issues in the conventional interface, or will the "i" button be added to the conventional interface? Or will "AU" be the only interface option and the proposed "mobile" interface is a trimmed version of the "AU" interface?
  • James 05Sep14: Yes, AU14 interface is optional. Yes, "i" button is AU14 interface only. I'm not too worried by this discoverability issue on the conventional interface as these tooltips are discoverable via prefs, problem is flagged as only a P5 (and I agree it's only P5), the interface will be superseded by AU14 interface, and issue could be completely addressed by adding one entry (Edit->Set Tool->) leading to a submenu, which is OK solution for conventional interface from my perspective. I feel it's better use of my energy/time to come up with an excellent solution for AU14 interface, rather than do whatever persuasion and compromise is necessary to get consensus on a solution in the current interface. As for the "mobile" interface, I think for 7" screens and below that will be a cousin of Audacity rather than a cut-down version. There is no hover on mobile, and often no physical keyboard, so it may well not have tooltips at all or configurable key-bindings. "Mobile" is over the horizon at the moment. What we've talked about and prototyped is more about getting to real time and proper plug-in API for tracks.
  • Gale 05Sep14: "AU14 interface is optional" and "the interface will be superseded by AU14" appear contradictory. Do you mean that you perceive most users will prefer the AU 14 interface when it is settled down, or that there is a planned Audacity version by which AU14 interface will be mandatory?
  • James 06Sep14: My plan is that most users will prefer the AU14 interface. I don't know if other developers will want to port features it already has to the existing interface, (smoothly zoomable rulers, multiple selections, loop-play whilst changing boundaries). If that happens, then the two interface will gradually become indistinguishable. Much more likely is that development of new code moves over to the AU14 interface, with just some bug fixing on the old. AU14 will be supporting the 'all-in-one-file' format. It makes sense to me that we drop the old user interface at some point, and switch to the new file format too, but we aren't always sensible. Timescales? Very hard to guess. I feel as if I am being asked to hold off on getting most of AU14 into Audacity for about a year, i.e. users first see the new rulers and multi-selection in September 2015. I would say from when it's distributed with Audacity as an optionally enablable plug-in to the point where most users will prefer it is another year from then, and then a third year before we seriously contemplate turning off the old interface. All just guesses though.
There is only one 'i' button. You can see it here. When down the info panel shows, and information in the lower part of the info panel is about whatever the cursor is over.

  • Peter 08Sep14: James wrote on the page "We do not need to show shortcuts in the tooltip. Having a button IS a shortcut for mouse users. Keyboard users can learn the keyboard shortcut keys from the menus, or from the key-bindings preferences. "
+1 to that. I would like to see us remove the shortcuts from the button tooltips for 2.0.7 - for a start I agree with James the button IS a shortcut and furthermore not all of them are currently entirely accurate (as discussed elsewhere on e.g. Play and Stop with the missing explicit "Space", see: ).
  • Gale 09Sep14:
I believe James and I are agreed that if hover tooltips for a toolbar do not show shortcuts then those shortcuts should be in the menu items for that toolbar or in an information bar. Note that Tools Toolbar has no menu equivalent at present. See for why the current shortcuts in the hover tooltips for Transport Toolbar or not wrong (just unintuitive). I also think James and I agree that e.g. the Play button tooltip could not really show the bindings for all of standard, loop and cut preview play.
  • James 09Sep14: Consensus....
So for 2.0.7 we add menu items for buttons that don't have them yet. And we remove keybinding info from tooltips.
For AU14 track panel, we work on making the smart help good, and tooltips will not have keybindings.
  • Gale 10Sep14:
Well, consensus so far :=) I still regard shortcuts in tooltips as user-friendly, just not practical for more than one binding. I really do not want the extra menu items for Tools Toolbar in Edit Menu given . How about that Tools Menu that Steve wants?

Older discussion


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.

Gale: I'd think people on large screen/high-res systems might prefer an extension to the Preferences panel, but we can't rely solely on that because others will not have such systems. So, either an option to choose a separate window or extended panel, or only a separate window. Another possibility you could consider for the extended panel would be the sort of sliding gizmo we used to have for Metadata Editor: it could slide back in when you click anywhere else in the panel, or switch to the new text if you click the help for another static box.

One advantage of having a separate window that is actually the highlighted section of the manual is that encourages the manual as a whole to be left open and read. Rather than doing that by having a modeless window like our Welcome Screen, I like how Goldwave opens the manual at the relevant point in a separate window whenever you click "help" in a Preference or Effect. You can then task switch between the Manual and the main app. I don't know about the accessibility issues of this, but it's what we do when opening a new project, and overall, this would be my choice for handling Preferences help, with tooltips at the level of our current longer in situ text.

What you've described with the trigger-based help scroller sounds a very interesting alternative which has some advantages over tooltips (ones you've described, and the reduced visual intrusiveness in random places). However, in order to replace tooltips and function as readily visible help, I think it needs to be "always on" while the Preference to enable it is checked. This would mean it does not rely on clicking a Help icon or your triggers to initially activate it. Instead, when you open Preferences on first launch it either shows the first static box, or (better) a sentence or two that describes the purpose of the Audio I/O tab. The manual does not have this, but that is easily fixed, and probably a good idea anyway.

If the help scroller is always on when enabled, then we could simply add a button at a later stage once the manual is built-in: "View Manual". It opens the Manual in a new window at the relevant highlighted section, and has the benefits I cited above. However (as I think you're already intending) the Preferences help scroller disappears when Preferences are closed, even if that help scroller is a separate window.

My opinion would be that if we're forsaking hover tooltips, then merely tabbing to a control, or selecting it without changing it (as you might do with a combo box) should switch help to the current static box when it's not already there.