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

From Audacity Wiki
Jump to: navigation, search
(Examples: replace the Microsof examples with Audacity examples)
(American spellling thru-out. Quick reference comes first.)
 
(63 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{note|1=
+
__NOTOC__
'''Peter 10Jun16:''' This page is a set of draft guidelines for when and where to use capitalization in the Audacity GUI.
+
{{note|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|'''title caps''']] (also referred to as book title capitalization) and
 +
*[[#sentence_caps|'''sentence caps''']] (also known as sentence-style capitalization).
 +
There is a [[#reference|'''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?".}}
 +
{{tip|1=
 +
See the Manual's Consistency page for guidance on [https://alphamanual.audacityteam.org/man/Consistency_in_wording_and_punctuation_in_Audacity#Wording_and_punctuation '''Wording and punctuation''']
 +
* We use American spelling throughout
 +
* We have made consistency decisions on many hyphenations and similar, listed on that page}}
 +
 
 +
 
 +
<div id="reference"></div>
 +
 
 +
==Quick Reference==
 +
This at-a-glance reference demonstrates when and where to capitalize in the UI.
  
The initial guidelines are taken from the [https://msdn.microsoft.com/en-us/library/windows/desktop/bb246428%28v=vs.85%29.aspx Microsoft guidelines] -  we can all comment here on what if anything we want to change.
+
:<span title="Quick Reference for capitalization guidelines">[[Image:capitalization guidelines.gif|link=]]</span>
  
I'm deliberately using '''note''' divs rather than '''ednote''' divs as some non-editors may well be reading and wanting to comment on the content of this page - and they should be able to see all the notes. }}
 
  
:<span title="This page is a Work in Progress">[[Image:WIP.png|center|frame|Work in Progress...|link=]]</span>
 
__NOTOC__
 
{{note|Correct capitalization helps readers identify important words and breaks in text. Two styles of capitalization appear in user interfaces:
 
*[[#title_caps|'''title caps''']] (also referred to as book title capitalization) and
 
*[[#sentence_caps|'''sentence caps''']] (also known as sentence-style capitalization).
 
There is a [[#reference|'''Quick Reference''']] image to illustrate the guidelines.}}
 
  
 
<div id="title_caps"></div>
 
<div id="title_caps"></div>
 
==Title Caps==
 
==Title Caps==
{{note|'''Peter 10Jun16:''' Vaughan wrote in a related email thread: ''"Fwiw, I was schooled in Apple's HIG, where every dialog heading is considered more or less like a book chapter title, so all nouns and verbs capitalized."'' }}
 
 
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.).
 
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:===
 
===Use title caps for:===
Line 25: Line 35:
 
*Column headings
 
*Column headings
 
*Command button labels
 
*Command button labels
..................................
+
*Multi-choice menus
*Web and Web-like page titles
+
*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)
 
*Web and Web-like navigational elements (unless prohibited by the page design)
*Floating toolbars
 
*ToolTips
 
..................................
 
*Tab titles
 
*Palette titles
 
*Icon labels
 
{{note|'''Peter 11Jun16:''' from this list I don't think that in Audacity we have: Palette titles, Tabs or Tab titles, or Icon labels - ''we may get Palette stuff later if and when we reintroduce theming or color choices for track name display on the waveform.'' 
 
*We do have a few web/web-like things in Audacity but these are restricted to links to our Manual and our Website.
 
*Although we can float our toolbars none of them carries any direct text so maybe we can omit this.
 
*I really don't agree with Microsoft here regarding ToolTips, I really think these should be in Sentence Caps - and that is what we seem to do in Audacity anyway.  And what's the difference between an InfoTip and a ToolTip?
 
}}
 
  
 
===Examples===
 
===Examples===
Line 45: Line 50:
 
*Check for Updates
 
*Check for Updates
 
*Regular Interval Labels
 
*Regular Interval Labels
 +
  
 
<div id="sentence_caps"></div>
 
<div id="sentence_caps"></div>
 +
==Sentence Caps==
 +
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.
 +
 +
Also, Tooltips, Infotips and Status Bar messages that explicitly refer to menu items take the title caps of those items. For example if we wanted to be verbose, the Trim button tooltip could say "Trim Audio - keep only the selected audio".
 +
 +
* Text does not end with a period, unless it's a complete or near-complete sentence in message box text or introductory/explanatory text in a dialog box.
 +
 +
* Tooltips, Infotips 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. If there is more than one sentence, all sentences must end in a period.
 +
 +
* Don't write a one-word sentence in message box or introductory/explanatory text followed by a complete sentence. For example this looks odd:
 +
{{codelist|Error.<br> Cannot export more than 1 million samples.}}
 +
:Make a complete sentence instead:
 +
{{codelist|Error: Cannot export more than 1 million samples.}}
 +
:or put the one word into the dialog title if possible.
 +
  
==Sentence Caps==
 
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.
 
  
 
===Use sentence caps for:===
 
===Use sentence caps for:===
*Check box labels
+
*Checkbox labels
 
*Text box labels
 
*Text box labels
 
*Option (radio) button labels
 
*Option (radio) button labels
*InfoTips
 
*Status bar tips and messages
 
*Messages
 
*Dialog box introductory or explanatory text
 
 
*List box entries
 
*List box entries
 
*List box labels
 
*List box labels
..................................
 
*File names
 
 
*Group box labels
 
*Group box labels
*Alternate text (ALT text) used to describe images
+
*Tooltips 
{{note|'''Peter 11Jun16:''' In Audacity I don't think we have Group boxes or ALT text to describe images.  Note that we curruntly do not observe these Microsoft guidelines in regard to the filenames that we generate in Audacity for things like configuation files or AutoSave filenames - nor in our files for Audacity releases - so maybe we should omit the File names entry. }}
+
*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===
 
===Examples===
*Working folder
+
*Retain labels if selection snaps to a label edge
*Print to
+
*Click and drag to select audio
*Use PostScript driver
+
*Ergonomic order of Transport Toolbar buttons
  
<div id="reference"></div>
+
==See also==
 +
*[https://en.wikipedia.org/wiki/Human_interface_guidelines Human interface guidelines] Wikipedia article
  
==Quick Reference==
+
*[https://msdn.microsoft.com/en-us/library/windows/desktop/bb246428%28v=vs.85%29.aspx Microsoft guidelines on Capitalization]
This at-a-glance reference demonstrates when and where to capitalize in the UI.
 
  
:<span title="Quick Reference for capitalization guidelines">[[Image:capitalization guidelines.gif|link=]]</span>
+
*[https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/OSXHIGuidelines/TerminologyWording.html Apple's UI design guidelines]
  
 
+
*[http://guijournal.com/2011/04/gui-design-capital-idea/ Graphical User Interface Design Notes] by Carl Andersen
==See also==
 
[http://guijournal.com/2011/04/gui-design-capital-idea/ Graphical User Interface Design Notes] by Carl Andersen
 

Latest revision as of 18:11, 19 January 2018


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?".
Bulb icon See the Manual's Consistency page for guidance on Wording and punctuation
  • We use American spelling throughout
  • We have made consistency decisions on many hyphenations and similar, listed on that page


Quick Reference

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

Capitalization guidelines.gif


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

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.

Also, Tooltips, Infotips and Status Bar messages that explicitly refer to menu items take the title caps of those items. For example if we wanted to be verbose, the Trim button tooltip could say "Trim Audio - keep only the selected audio".

  • Text does not end with a period, unless it's a complete or near-complete sentence in message box text or introductory/explanatory text in a dialog box.
  • Tooltips, Infotips 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. If there is more than one sentence, all sentences must end in a period.
  • Don't write a one-word sentence in message box or introductory/explanatory text followed by a complete sentence. For example this looks odd:
Error.
Cannot export more than 1 million samples.
Make a complete sentence instead:
Error: Cannot export more than 1 million samples.
or put the one word into the dialog title if possible.


Use sentence caps for:

  • Checkbox labels
  • Text box labels
  • Option (radio) button labels
  • List box entries
  • List box labels
  • Group box labels
  • Tooltips
  • 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

See also