Difference between revisions of "Guidelines on capitalization in Audacity dialogs and messages"

From Audacity Wiki
Jump to: navigation, search
(Still an unresolved query about one word "sentences" in message boxes.)
(Sentence Caps: reply to Gale)
Line 44: Line 44:
 
Ideally we would have Error in the title bar if that were possible. It looks odd to me as it is now. Should we make a complete sentence thus?
 
Ideally we would have Error in the title bar if that were possible. It looks odd to me as it is now. Should we make a complete sentence thus?
 
{{code|
 
{{code|
Error: Cannot export more than 1 million samples.}}}}
+
Error: Cannot export more than 1 million samples.}}
 +
*'''Peter 14Jun16:''' Yes I think so Gale - looks better to me that way. (and thanks for removing the "superfluous text" that I left behind.}}
 
Capitalize only the first letter of the first word, and capitalize only those other words that are normally capitalized in sentences, such as proper nouns. Proper nouns include explicit Audacity entities such as Track Control Panel, Transport Toolbar, Scrub Bar, etc.  
 
Capitalize only the first letter of the first word, and capitalize only those other words that are normally capitalized in sentences, such as proper nouns. Proper nouns include explicit Audacity entities such as Track Control Panel, Transport Toolbar, Scrub Bar, etc.  
  
Line 72: Line 73:
  
 
<div id="reference"></div>
 
<div id="reference"></div>
 +
 
==Quick Reference==
 
==Quick Reference==
 
This at-a-glance reference demonstrates when and where to capitalize in the UI.
 
This at-a-glance reference demonstrates when and where to capitalize in the UI.

Revision as of 15:04, 14 June 2016


These guidelines are provided to help developers create consistent communication with users via the Audacity GUI. They should certainly be helpful for new Audacity developers and save time and effort of tweaking GUI elements after a new feature has been coded (which can be quite irritating for a developer and QA alike). Correct capitalization helps readers identify important words and breaks in text.

Two styles of capitalization appear in in the Audacity User Interface:

  • title caps (also referred to as book title capitalization) and
  • sentence caps (also known as sentence-style capitalization).

There is a Quick Reference image to illustrate the guidelines.

Developers may sometimes intentionally choose to break these guidelines if they think that they do not fit their particular GUI element, or QA usability testing reveals an advantage in doing so. The fundamental guideline is - "Does it look better if capitalization is changed?".

Title Caps

Capitalize the first letter of the first and last words. Capitalize the first letter of all words in between, with the exception of articles (a, an, and the); coordinating conjunctions (and, but, for, nor, or, so, and yet); and prepositions of four letters or fewer (at, for, with, into, etc.).

Use title caps for:

  • Menu names and menu commands
  • Button names
  • Toolbars and toolbar button labels
  • Title bar text (for dialog boxes)
  • Column headings
  • Command button labels
  • Multi-choice menus
  • Floating toolbars - although we can float our Audacity toolbars, we do not label or title them (except with hover-text)
    • Note: If file names are included in elements that use title caps, the file name should be capitalised exactly as it is. So the title bar of the dialog to browse for Lame correctly says "Where is lame_enc.dll?" and does not capitalize any part of the file name.

We do not appear to have the following entities in Audacity. They are retained here in case we introduce them in the future.

  • Tab titles
  • Palette titles - we may get these later if and when we reintroduce theming or color choices for track name display on the waveform
  • Icon labels - we do not currently label any of our icons in Audacity
  • Web and Web-like navigational elements (unless prohibited by the page design)

Examples

  • Rescan Audio Devices
  • Bass and Treble
  • Check for Updates
  • Regular Interval Labels


Sentence Caps

Gale 14Jun16: Some effects (Nyquist) have "Error" (which is not a sentence) followed by a period then a sentence describing the error on the next line. For example

Error.
Cannot export more than 1 million samples.

Ideally we would have Error in the title bar if that were possible. It looks odd to me as it is now. Should we make a complete sentence thus?

Error: Cannot export more than 1 million samples.

  • Peter 14Jun16: Yes I think so Gale - looks better to me that way. (and thanks for removing the "superfluous text" that I left behind.

Capitalize only the first letter of the first word, and capitalize only those other words that are normally capitalized in sentences, such as proper nouns. Proper nouns include explicit Audacity entities such as Track Control Panel, Transport Toolbar, Scrub Bar, etc.

Text does not end with a period, unless it's a complete or near-complete sentence in message box text or dialog box introductory or explanatory text. Infotip and Status Bar messages do not end with a period, even if a complete or near-complete sentence, unless there is more than one sentence. This seems to be per Apple practice and that of many non-Microsoft applications on Windows.

Use sentence caps for:

  • Checkbox labels
  • Text box labels
  • Option (radio) button labels
  • List box entries
  • List box labels
  • Group box labels
  • Tooltips
    • Note: Where the tooltip is a button that operates a menu item, the tooltip should use the title caps of the menu item. For example if we wanted to be verbose the Trim button tooltip could say "Trim Audio - keep only the selected audio".
  • Infotips - An Infotip is a tooltip with a longer description, according to https://msdn.microsoft.com/en-gb/library/windows/desktop/dn742443(v=vs.85).aspx
  • Status bar text
  • Messages
  • Dialog box introductory or explanatory text
  • Web and Web-like page titles
  • Alternate text (ALT text) used to describe images - note though, we don't incorporate images as such in Audacity

Examples

  • Retain labels if selection snaps to a label edge
  • Click and drag to select audio
  • Ergonomic order of Transport Toolbar buttons


Quick Reference

This at-a-glance reference demonstrates when and where to capitalize in the UI.

Capitalization guidelines.gif


See also