Completed Proposal Help button for Preferences & Effects, Generators and Analyzers

From Audacity Wiki
Revision as of 13:54, 8 May 2017 by Galeandrews (talk | contribs) (+1 to Help buttons in dialogues requested by the user)
Jump to: navigation, search
Proposal pages help us get from feature requests into actual plans. This page is a proposal to provide help to users of preferences, effects, generators and analyzers.
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.

The Problem

  • Many of our Preferences have quite complex (and sometimes subtle) effects on the behavior of Audacity
  • Many of our effects, generators and analyzers are quite complex.
  • We know that many users do not bother to RTFM.
  • As policy we no longer have help text on plug-in dialogs.
  • We have other complex dialogs in the GUI (such as Spectrograms settings and other Preferences)

Proposed Feature

  • All dialogs for preferences to carry a "Help" button
    • Clicking on that button will take the user to the relevant page in the Manual.
    • Wordy preferences can be very much reduced. They take too much space and do not say enough. Users who don't know already what the preference does now will have a direct link into the manual.
    • We have a working prototype of help button with the Timer Record and Analyze>Contrast dialogs
  • All dialogs for effects, generators and analyzers to carry a "Help" button
    • Clicking on that button will take the user to the relevant page in the Manual
    • We have a working prototype with the Analyze>Contrast dialog
  • Consider also such Help buttons for Export/Import dialogs, Save Project dialogs
  • Also the (dismissable) warning messages when exporting an Audacity project.
See Bugzilla enhancement entry #1051 for tracking.

* Steve has proposed an iconic help button HelpButton.png to save space, provide consistency and attract the user's attention.

Developer/QA Backing

  • Peter: +1, Preferences first, for me. Much higher priority (and a smaller task) than the EGAs.
    • I am minded to agree with James about using Context Sensitive Help for the Preferences dialogs
    • Peter 02May17: I have changed my mind we have pefectly good documentation pages in the Manual so it is good to drive folk there (it may encourage them to read more of the Manual). Plus "context sensitive help" is in effect duplicatiing the "documentation" ad in doing so creates unnecessary extra work.
  • James 08May17: +1 for me for help buttons on preferences.
I still think we could in time do something nicer using context sensitive help, but a button right now gives good-bang-for-bucks. Relatively low effort, and allows us to shorten the wordy preferences. I'll vote again and comment on effects and such, once the prefs part is done.
  • Gale 08May17: +1 for Help buttons that go to the Manual in Preferences and effects (all three classes). This is not a +1 for a Help button in pop up dialogues that the user did not request. There, practical inline help (ideally, not much more text than we have now in a Preference option, and which may save the user going to the Manual) is first choice. Help button should be only if necessary.
The only real advantages I see in context-sensitive help are a) it would let us make the Preferences text less verbose b) If the user is only "browsing" and only needs a rough idea what the control does, the Manual may be overkill/TLDR.

Use Cases

Gale 08May17: Is the below statement still a use case for this Proposal?

Users do not read the Manual and this fail to understand preferences settings or complex effects, generators and analyzers.


  • Add Help buttons or Help icons to every Preference pane - there is easily sufficient room
  • Adding a button to the effects, generators and analyzers will increase button clutter
    • We can free button room by removing the "Debug" button from released tools (debug is not really appropriate for a released plug-in).
    • Instead of a new button we could add a new menu item to the "Manage" button dropdown menu. This is sub-optimal as it makes the help less discoverable.
    • Gale suggested by email: Can we make a small Help button with a question mark on it to be accessible?

Menu items with dialogs that would benefit from such a Help button

  • File menu
  • Save Project
  • Save Project As
  • Save Compressed Copy of Project
  • Edit Metadata Tags
  • Import
  • Export Audio
  • Export Selected Audio
  • Export Labels
  • Export Multiple
  • Apply Chain
  • Edit Chains
  • Edit menu
    • Preferences
  • View menu
    • History
  • Transport menu
    • Timer Record we already have this prototype working - it will be in 2.1.3
    • Sound Activation Level

Where should the Help button link to?

There has been some discussion on a recent devel email thread as to what the target of the Help button should be. Currently:

  • The Help button in Analyze>Contrast goes to whichever Manual the user has specified in Preferencse>Interface>Locationof Manual. Note that the default setting for this is "Local" and IF the user has a local installed Manual it will go there ELSE Audacity displays an error/warning message with a link to download the installed Manual, or just link to the required page on-line. Plus some advice is given re. the Preferences setting.
  • The Help button in Transport>Timer Record goes to the on-line Manual - and note that this requires that the user has an active internet connection. So this should be changed to mirror the Analyze>Contrast behavior.

For discussion on this please see the Talk Page.

GUI Examples

Timer Record setup dialog with Help button.png
The order of the buttons is controlled by the generic ShuttleGui class written by James. Looks like they should be left as is for consistency throughout the system.

Previous Feature Requests relating to this proposal

  • Links/buttons go to relevant help in the Manual (4 votes)
  • General (Effect menu items):
    • Useful if plug-in has displayable help files like some Nyquist plug-ins