Difference between revisions of "Proposal Smart Help"

From Audacity Wiki
Jump to: navigation, search
(Added header)
(Developer Backing: *'''Peter:''' I support this idea)
 
(5 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
== Proposed Feature ==
 
== Proposed Feature ==
  
Detailed context sensitive information on each configurable parameter in the preferences panel.  This information will be automatically extracted from the html help reference section which has been written with this use in mind.
+
Detailed context sensitive information on each configurable parameter in the preferences panel.  This information will be automatically extracted from the html help reference section which has been written with this use in mind.  Smart Help would also give context sensitive help on buttons, giving more information than can usefully fit in a tooltip.
  
  
== Developer Backing ==
+
== Developer/QA Backing ==
*[[User:James|James Crook]] I have done some development work which could be built on for this.  The most useful part is a change in [[Hacker's_Guide#ShuttleGui|ShuttleGui]].
+
*[[User:James|James Crook]] I did some initial development work which could be built on for this.  It is a change in [[Hacker's_Guide#ShuttleGui|ShuttleGui]] that allows sections of a dialog to be clicked on, to highlight in the help color, and to trigger an event that updates help text in another window.  Probably that mechanism is superseded by [[User:James/AU14TrackPanelTheming|the new theming interface]], the scroller which can be used for preferences too.  We'll be using dialogs far less.  Discussion has now also extended the smart help mechanism to take over where tooltips on buttons prove too limited.
 
+
*'''Peter:''' I support this idea
  
 
== Use Cases ==
 
== Use Cases ==
Line 17: Line 17:
 
* '''Audacity GUI as the index:''' Instead of reading the manual and finding the right place in it, Audacity can find the right place and just present the information you asked for.
 
* '''Audacity GUI as the index:''' Instead of reading the manual and finding the right place in it, Audacity can find the right place and just present the information you asked for.
  
 +
== Design ==
  
== See Also==
 
  
* [[More GSoC Ideas#Smart Help Infrastructure|Smart Help]]
+
=== For preferences ===
* There's some text that should move here on [[Proposal Preferences Reorganisation|prefs reorg]]
+
* Interleaving comments with settings in a multiscroller works well.  An example is shown on the [[User:James/AU14TrackPanelTheming|page about theming]].  This can and should be extended to support hyperlinks, to dig deeper in the manual.  This would open a browser window.  The comments in this scroller can address groups of related settings.  The scroller design means that it is usable on space constrained screens, netbooks, yet can make good use of more vertical space if it is available.  This was previously a problem with preferences where we had to break the preferences up into 'same sized' categories.
  
 +
=== For button tooltips ===
 +
* The 'information' button, the i with a circle round it, can show/hide a panel with additional information.  When the 'i' button is down, the panel shows and the lower part of the panel has information from the manual.
 +
: The information panel can have information that changes as the tooltips show and hide.  Most usually the panel will have general information about a toolbar, and information about buttons in it would highlight as you move from button to button.  The information panel hyperlinks, to dig deeper in the manual. 
 +
: The panel is not full screen, so it is not suitable for displaying manual pages that have wide screenshots in them.  We might need to rejig the manual a little to ensure we have pages suitable for the panel.  This could be markup on key landing pages to exclude wide images and related text.  Hyperlinks from the panel will open a full browser.
 +
* 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.
  
 +
=== Multi-function buttons ===
 +
* Multi-function buttons, where different functions are accessed by a modifier key (shift, ctrl, alt, ctrl + shift) have many problems.  We could, for example, have whistle-triggered-record accessed from record via a modifier key.  If we did this, we'd be mixing heavily used and esoteric features and making the interface more confusing.  That said, multi-function buttons can save screen space.  Looped play is very useful, and arguably it does belong with normal play.  Generally Multi-function buttons need a rethink.
  
==Discussion==
+
** '''Click-and-hold''' on a toolbar button could drop down more options.  Effectively the button becomes the head of a menu.  Chrome does this with the back-button, where click and hold on the back button shows browser history and a choice of pages.  Click-and-hold gives more options.  In Chrome, the tooltip is: 'Click to go back, hold to see history'.
 +
** With this change, it would be OK to still retain the modifier keys.  However, we do not need to advertise the modifier key in the tooltip.  'Click to play audio, hold for more play options' would be a possible tooltip.  Click and hold then gives a mini-menu that includes loop-play as an option, and showing shortcut key combinations.  That menu can have lots of options, play, loop play, play-excluding, play-at-speed, loop-play-at-speed, play-through, play-with-swearwords-bleeped and so on.  When a modifier key is held down, the icon can, if we want, still change, and the tooltip can change, e.g. hold down shift and the tooltip becomes 'loop play'.  It's become a minor feature, rather than crucial to discoverability.
 +
** '''Customisable buttons''' advanced users (I am thinking 1% of users) may enjoy customising their toolbars, adding optional buttons, so that they have both a button for looped play and play, and possibly buttons for some preset speeds, e.g. play x2.  Once users break out the options, we shouldn't be changing the icons based on a modifier key being down. 
  
 +
=== For menus ===
  
'''[[User:James|James]]:'''
+
* The information panel can work for menu items in the same way as it does for buttons.  The discussion above shows that buttons are just a different visual design for a menu.
 +
 +
=== What else is on the information panel? ===
  
Current design difficulties:
+
* The top item in the information panel is the 'mode' audacity is running in, standard, custom or full.  The panel will contain information about the currently loaded projects, file size, location, disk space.  Advanced users will be able to customise this display so that it has more information that they choose.  The idea is that the information panel will be useful to advanced users too, and so justify having a large button on the toolbar.
  
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?
+
== See Also==
  
 +
* [[More GSoC Ideas#Smart Help Infrastructure|Smart Help]]
 +
* [http://ux.stackexchange.com/questions/4067/context-sensitive-help-for-wordy-user-preferences Q&A at Stackexchange UX]
 +
* There's some text that should move here on [[Proposal Preferences Reorganisation|prefs reorg]]
  
'''[[User:Galeandrews|Gale]]:'''
 
 
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:
 
 
# An additional help window (either disappears when preferences are exited or not)
 
# Same idea, but integrated with the inbuilt help, so there is no need to write extra text
 
# 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.
 
 
'''[[User:James|James]]:'''
 
 
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.
 
 
'''[[User:Galeandrews|Gale]]:'''
 
 
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? 
 
 
: '''[[User:James|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.
 
 
 
'''[[User:Galeandrews|Gale]]:'''
 
 
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. 
 
 
: '''[[User:James|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.
 
 
 
'''[[User:Galeandrews|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 revelant 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.   
 
  
  
 
[[Category:For Developers]]
 
[[Category:For Developers]]
 
[[Category:Feature Planning]]
 
[[Category:Feature Planning]]

Latest revision as of 16:33, 18 February 2021

Proposal pages help us get from feature requests into actual plans. This page is a proposal for context sensitive help in the preferences panels.
Proposal pages are used on an ongoing basis by the Audacity development team and are open to edits from visitors to the wiki. They are a good way to get community feedback on a proposal.


  • Note: Proposals for Google Summer of Code projects are significantly different in structure, are submitted via Google's web app and may or may not have a corresponding proposal page.


Proposed Feature

Detailed context sensitive information on each configurable parameter in the preferences panel. This information will be automatically extracted from the html help reference section which has been written with this use in mind. Smart Help would also give context sensitive help on buttons, giving more information than can usefully fit in a tooltip.


Developer/QA Backing

  • James Crook I did some initial development work which could be built on for this. It is a change in ShuttleGui that allows sections of a dialog to be clicked on, to highlight in the help color, and to trigger an event that updates help text in another window. Probably that mechanism is superseded by the new theming interface, the scroller which can be used for preferences too. We'll be using dialogs far less. Discussion has now also extended the smart help mechanism to take over where tooltips on buttons prove too limited.
  • Peter: I support this idea

Use Cases

  • Shorter descriptions: 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.
  • Audacity GUI as the index: Instead of reading the manual and finding the right place in it, Audacity can find the right place and just present the information you asked for.

Design

For preferences

  • Interleaving comments with settings in a multiscroller works well. An example is shown on the page about theming. This can and should be extended to support hyperlinks, to dig deeper in the manual. This would open a browser window. The comments in this scroller can address groups of related settings. The scroller design means that it is usable on space constrained screens, netbooks, yet can make good use of more vertical space if it is available. This was previously a problem with preferences where we had to break the preferences up into 'same sized' categories.

For button tooltips

  • The 'information' button, the i with a circle round it, can show/hide a panel with additional information. When the 'i' button is down, the panel shows and the lower part of the panel has information from the manual.
The information panel can have information that changes as the tooltips show and hide. Most usually the panel will have general information about a toolbar, and information about buttons in it would highlight as you move from button to button. The information panel hyperlinks, to dig deeper in the manual.
The panel is not full screen, so it is not suitable for displaying manual pages that have wide screenshots in them. We might need to rejig the manual a little to ensure we have pages suitable for the panel. This could be markup on key landing pages to exclude wide images and related text. Hyperlinks from the panel will open a full browser.
  • 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.

Multi-function buttons

  • Multi-function buttons, where different functions are accessed by a modifier key (shift, ctrl, alt, ctrl + shift) have many problems. We could, for example, have whistle-triggered-record accessed from record via a modifier key. If we did this, we'd be mixing heavily used and esoteric features and making the interface more confusing. That said, multi-function buttons can save screen space. Looped play is very useful, and arguably it does belong with normal play. Generally Multi-function buttons need a rethink.
    • Click-and-hold on a toolbar button could drop down more options. Effectively the button becomes the head of a menu. Chrome does this with the back-button, where click and hold on the back button shows browser history and a choice of pages. Click-and-hold gives more options. In Chrome, the tooltip is: 'Click to go back, hold to see history'.
    • With this change, it would be OK to still retain the modifier keys. However, we do not need to advertise the modifier key in the tooltip. 'Click to play audio, hold for more play options' would be a possible tooltip. Click and hold then gives a mini-menu that includes loop-play as an option, and showing shortcut key combinations. That menu can have lots of options, play, loop play, play-excluding, play-at-speed, loop-play-at-speed, play-through, play-with-swearwords-bleeped and so on. When a modifier key is held down, the icon can, if we want, still change, and the tooltip can change, e.g. hold down shift and the tooltip becomes 'loop play'. It's become a minor feature, rather than crucial to discoverability.
    • Customisable buttons advanced users (I am thinking 1% of users) may enjoy customising their toolbars, adding optional buttons, so that they have both a button for looped play and play, and possibly buttons for some preset speeds, e.g. play x2. Once users break out the options, we shouldn't be changing the icons based on a modifier key being down.

For menus

  • The information panel can work for menu items in the same way as it does for buttons. The discussion above shows that buttons are just a different visual design for a menu.

What else is on the information panel?

  • The top item in the information panel is the 'mode' audacity is running in, standard, custom or full. The panel will contain information about the currently loaded projects, file size, location, disk space. Advanced users will be able to customise this display so that it has more information that they choose. The idea is that the information panel will be useful to advanced users too, and so justify having a large button on the toolbar.

See Also