Consistency

Impartiality
Please do not add first person opinions. "I" or "my" are not allowed.

Wording and punctuation
These are our suggested guidelines for consistency in wording. Please add to them, or comment if a change is thought desirable.

This seems closest to general usage and makes it the most distinct from surrounding text without confusing due to the period (though strictly, that is more correct).
 * US English ... examples:
 * "behavior" not "behaviour"
 * "check/uncheck the box" not "tick/untick the box"
 * "color" not "colour"
 * "dialog" not "dialogue"
 * "gray/grayed" not "grey/greyed"
 * "labeling" not "labelling"
 * "normalize" not "normalise"
 * Abbreviations should not be used for commonly used phrases - "for example", not "e.g."; "and similar", not "etc."
 * Audacity when used as the proper name of our editor must be capitalized - "Audacity", not "audacity".
 * Click versus Press versus Hit versus Choose: "Click" on a button UI element, not "press"; "Choose" an item from a menu or a list, not "click" ; "Press" a keyboard key, not "hit" it.
 * "Command-line", not "Command line"
 * Commas (multiple): when used in a sentence or phrase should not include the final comma, so should not be used at all to divide two concepts, for example, "use the amplify or normalize effect" not "use the amplify, or normalize effect" and "the advantages are in accessibility, portability and cheapness" not "the advantages are in accessibility, portability, and cheapness"
 * Crossfade, not "cross fade" or "cross-fade" EXCEPT when discussing Audacity's "Cross Fade In" and "Cross Fade Out" effects (which do not perform crossfades).
 * File formats should be fully capitalized without preceding period (full stop), so:
 * "MP3", not "Mp3", "mp3" or ".mp3"
 * File name (two words) not "filename".
 * Fractions are usually written out as text for clarity, and hyphenated: "two-thirds" not "2/3 or "two thirds".
 * Frequencies: Use values in Hz, not kHz in almost all cases. This matches with the Audacity interface almost everywhere, and prevents confusion in novices if mixing units. For example, "the frequency can vary between 200 Hz and 2 kHz" is very strongly discouraged. If it is necessary to refer to a UI element where kHz is actually displayed (for example, in the Graphic EQ slider tooltips), then kHz should be used with the corresponding Hz value in brackets for comparison.
 * Hyphens:  "right-click" and "double-click" not "right click" and "double click" ; "downward-pointing" not "downward pointing"; "drop-down" not dropdown. Note that there are no spaces between the hyphen. If separating clauses in a sentence, use a single hyphen with a single space either side. Always use hyphens; dashes (longer) in text are not allowed.
 * Internet:  "e-mail" not "email"; "web site" not "website"  (although modern usage often favours "email" and "website", it isn't logical)
 * Keyboard or mouse shortcuts should be referred to as "shortcuts", not "hotkeys". Use upper case, and "+"  not "-" to separate key presses (generally, this should make them more readily understood), so "CTRL + 1" not "CTRL-1"  or "ctrl-1". The actual shortcut should be included inside   tags as described at Spans and Divs.
 * Menu paths are formatted inside  tags ( or  ) and navigation arrows should be indicated by " > ", not "->".
 * Numbers have no spaces or commas ("44100 Hz", not "44,100 Hz " or "44 100 Hz"). Any numbers over a million (probably none) we'll consider if they arise. Generally, numbers less than 10 are written out as text ("five tracks" not "5 tracks", "this happens two times" not "this happens 2 times"). An exception to this is where the number is a unit of measurement - hence "0.5 seconds" is preferred to "half a second", and "4 bits" to "four bits".
 * Quotes are inside double quotes, not single, so " ", not ' '
 * Software/hardware terminology: opinions vary but we choose the most common pro usage or the most common in US English if there is no consensus:
 * "cut-off" (noun), not "cutoff" or "cut off"
 * "resampling", not "re-sampling"
 * "rolloff" (noun), not "roll-off" "or roll off"
 * "sound card", not "soundcard"


 * "in synchronization", not "in sync"; "synchronized" not "synced" unless explicitly referring to an Audacity GUI element that says "Sync"*
 * Units: "dB" not "db", "seconds" and "milliseconds" not "s" and "ms". "inch" or "inches", not '' or ". "mm" is acceptable for millimetres. There must always be a space between the value and the unit (for example, "10 dB" not "10dB").

GUI Elements

 * "dialog", not "window" or "dialog window" (for all windows that open as a result of doing something else in the project window)
 * "mouse pointer", not "mouse cursor"
 * "plug-ins", not "plugins" or "Plug-Ins"
 * "Selection Formats" not "Time Formats" or "Time Units"
 * To detail selection formats we say these are "various time units, samples or media frames" or (longer) "various time units, samples, audio CD frames or film frames"
 * "selection region", not "selection area" because menus refer to "regions"
 * "Timeline", not "ruler" or "horizontal ruler" or "time ruler"
 * "Time digits" not "Time values" for TimeText spin boxes as in Selection Toolbar
 * To describe what the "time digits" are in Selection Toolbar, say they are "digits representing time or other formats".
 * "Time Shift Tool", not "Move Tool"
 * "Track Drop-Down Menu", not "Track Pop-Down Menu" (items "drop" down or "pop" up)
 * "Toolbar", not "Tool Bar"

Glossary
Technical words or phrases should be linked to in the glossary rather than explained in situ as a one-off. Glossary links are surrounded by five (5) sets of single-quotes, which makes them bold italic. Please keep them non-capitalised (unless at the start of a sentence). They are probably best avoided in summary "quick text" (which should avoid the need for them where possible) but should be used the first time the word or phrase is used in detailed text.

Example:

This is a logarithmic scale.

Which gives:

This is a logarithmic scale.

-

Glossary link information:

DISPLAY TEXT

"Glossary" designates the Glossary page, and is also used as the hover text. #link must not contain spaces and is case sensitive. Currently all links are in lower case and do not contain colons. Use underscores for spaces. Thus the link for Hz is #hz, AIFF is #aiff, MP3 is #mp3, and Dynamic range is #dynamic_range.

Note that some link names are not straightforward. Notably, logarithmic is #log, dB is #decibel, Ogg Vorbis is #ogg, and Audio CDs is #audio_cd. If you have any question, view the source of the Glossary page and search for '<td id="xyz'.

Note: We have a practice of capitalising all words in the the Glossary listing itself so stick to that for the sake of consistency.

Page titles
Generally, we stick to Wikipedia guidelines for page titles.
 * Do not capitalize the second or subsequent words in an article title, unless the title is a proper noun.
 * Do not use CamelCase (compound capitalized words).

In a Manual the first bullet point above can be interpreted with some freedom as even something like an activity can arguably be thought of as a proper noun. In practice, we tend to capitalise subsequent words more often than not, and the guiding principle should be what is best for the reader.

Headers
{{ednote|1=Ed 29May13: samples (here for comparison): H1 headings do not seem to be authorized (except as the title)... =H1 heading= but exist. H2 headings share the underline:

H2 heading
but H3 (and above - smaller) do not:

H3 heading
H4 (as well as 3 & 5) are bolded:

H4 heading
H5 is the smallest authorized header:

H5 heading
but IMHO is too small for any general usage. Note the built-in pre- & post-spacing.}} The page title will render as a first order heading, so place the primary headers in your text inside second order tags (two equals signs) thus:

== Primary heading ==

Use incremental headings in the structure, so that second level headings in your text are third order headers:

=== Secondary heading ===

then third level headings are inside fourth order headers and so on.

Capitalization of headers: If the header describes an interface item, be sure to respect the capitalization of that item as it appears in the interface. Otherwise, capitalize only the first word (except that any proper names should be capitalized wherever they occur).

Spacing: Stick to one line of space before each of the different order headings. The CSS has now been changed to add a little more space above H2 headings.

Non-headered headings
These are not enclosed in == headers and may or may not be preceded by a bullet. These headings must be in bold, must end with a colon, and the first word of the following text should be capitalized viz:

Device: Selects the Device for playback.

Again, always capitalize the first word of the heading, and respect the capitalization of a menu item as is.

Paragraphs
Always use paragraphs, not line breaks, to separate blocks of text consistently with one line of white space. This applies also to separating blocks of text in templates and divs and in lists. To ensure paragraph formatting remains inside the current list bullet, start the paragraph on the same line with  and end it with.

Page anchors
Use divs of the form   to provide anchors to headings or to any other location within a page that can be linked to from other pages. The objective of an anchor is to be internet compliant and as short as possible for usage in technical support e-mails. Therefore, contractions such as shortening "toolbar" to "bar" are fine in an anchor. When linking to an anchor, preface the "name_of_anchor" with a #, for example Selection Toolbar's snap feature. If you are linking to an anchor that is on the same page, only the "#" and the name of the anchor are needed (you can omit the preceding page title) .
 * As with page titles, CamelCase (compound capitalized words) is not used.
 * Capital letters should not be used at all.
 * Do not use spaces in an anchor - connect separate words or phrases with underscores instead.

Page families
Pages may fall into families according to their purpose and pages within a family should share the same style of layout. Layout to use for some families is still being discussed.

Decisions made:


 * individual Preferences tabs:
 * enclose the name of each static box or panel section inside second order headers (==)
 * then use a bulleted list for items within the static box or panel section. The first text in each list item should be the name of the item within the box or section, followed by a colon, both in bold. The first word of the succeeding text should be capitalized. For example:


 * Axis: Determines if a linear or logarithmic scale is used.


 * individual Menu pages:
 * Each menu item is enclosed in second order tags e.g. ==Remove Audio==
 * Submenus are enclosed in third order tags e.g. ===Split Delete===
 * The Edit Menu is a special case requiring a custom index due to its length and complexity.


 * Historical note: The idea of starting each menu page with an image of the menu and "quick text" decribing each menu item beside the menu image (using a table) has been abandoned. It proved very difficult to write text that explains enough, without becoming merely a summary duplication of the main text, and without becoming too long in the long menus like File Menu. The wasted white space to left of the quick text was another problem.


 * Toolbars Overview.
 * See the examples at: Edit Toolbar, Tools Toolbar and Transport Toolbar - and the comments thereon.

Note on use of templates versus spans and divs
Before May 2012 all text highlighting and "info boxes" were created using spans and divs respectively.

Since then templates are required for the advice and alert boxes. Intro, note and ednote boxes can be created with divs or templates at the editor's discretion.

Editors can continue to use either a template or a span for text highlighting. However, templates are required for the "on-screen button" highlighting that includes an image of the button element (checkbox, radio button or dropdown menu triangle).

Templates require less typing. Editors are encouraged to use templates in new text.

If the text in a box exceeds a few lines, start a new paragraph (not just a new line) at a logical break in the text.

The intro box
... or
 * For use at the top of many pages to highlight an introductory paragraph that summarizes the following contents. Generally the intro should not exceed five or six lines, and would not be needed unless the main text was several paragraphs long.


 * Use the div below if what you are highlighting is not at the top of the page.

The note box
... or
 * The main use is as a "tip" or "hint" - extra non-essential pieces of information which may be of particular interest only to a subset of users, or to someone who already knows 90% of what has been written and is just skimming.
 * Another valid use (but only with considerable discretion and say, only once per three or four scrolls) is to highlight information, merely to break up the text a bit. Consider an image in preference to break the text up, as that may actually save some text.

The advice box

 * Use in exceptional circumstances to highlight some text with yellow background and a warning icon that describes something that requires care or attention. It is more important than a note but less dire than an alert. For example, use it in a case like this:

The alert box

 * Use in exceptional circumstances to highlight some text with pink background that describes something that is dangerous or should never be done. For example, use it in a case like this:

The example box

 * Use to encase and highlight a worked example:

The editornote box
... or Editor'sName 31Jan12: a note Name 1Feb12: a new note topic
 * The only use is as a means of conversing between editors. It is only visible to logged in editors. Editors are encouraged to include their name and the date in bold for any such note:
 * Another Editor's name 1Feb12: reply indented to display to which message the reply correlates.
 * Editor'sName 31Jan12: a reply to the previous reply

The menu highlight
... or For use to highlight a sequence of menus, buttons or similar with orange background. For example, use it in a case like this:
 * to produce.

This is only for use for a navigation sequence. A single button, menu or GUI element (e.g. a Preview button when you reach the intended dialogue) should not be formatted with this span. Normally (at least in first use in a page), a menu sequence will link to the appropriate endpoint anchor in the Manual. In this case, we only make the anchor take a link, so that the user only has one link to click on to reach the anchor, but still realises that two clicks are needed in the menus. Example:
 * Any menu selection is considered a "sequence" as it requires two clicks to make the menu selection.
 * An instruction to check the state of a menu item should not be formatted with this highlight. For example:
 * Choose the "Transport" menu and make sure that "Sound Activated Recording (on/off)" is not checked.
 * On screen buttons that have text should be formatted with the button template and its variants (see below).
 * which is written as:
 * File > Check Dependencies... '''
 * or alternatively as:

Special menu highlight for use in advice boxes: menuadvice

Special menu highlight for use in alert boxes: menualert


 * Bill 12May12: I have a query about navigating to, for example, a preference pane and then a selection therein. For example, do we write:
 * Choose ...or do we write Choose, then select the Recording tab ...

I do not like the former as it suggests that "Recording" is a sub-menu of "Preferences".
 * Similarly for: Choose ... versus Choose  then the Sound Panel ...
 * Gale 13May12: I think "Edit > Preferences" is probably out because of Mac. If we were to use it and accept it' s wrong for Mac, then is my choice. On the whole I think the better answer could be "Go to the  then choose the  section". I have become a bit disenchanted with using "tab" for the section of Preferences, though I think it's better than "pane" or "page". We need to change the editorote div colour so we can see menu spans.
 * Bill 13May12:
 * I agree that "Go to the then choose the  section" is preferable. I usually write "section" instead of "tab", since they are not, strictly speaking, tabs.
 * We can change the editornote colour, or we can use menuadvice just for visibility in editornotes.

The shortcut highlight
... or
 * For use to highlight a keyboard or mouse shortcut with purple-gray background and bold, italicized text. Use fully capitalized text when typing the shortcut. For example, use it in a case like this:  CTRL + A or  to produce CTRL + A.

 Use shortcut spans or templates also for the SHIFT component of a SHIFT-modified click or arrow press, for example:  hold SHIFT and click in the track  hold SHIFT while using or .  Use shortcut spans for unmodified keys when they quality as a shortcut  press the C key to hear the audio 2 second before and 1 second after the selection  press SPACE to start playback </ul>  In general, any shortcut listed on Keyboard Shortcut Reference should be highlighted with this span or template, as should a modifier used with the mouse in Mouse Preferences.  Do not use shortcut spans or templates for pressing a key on its own when it is not part of a shortcut. In these cases, use the kbrd span or template (see below). See the examples at Metadata Editor.</ul></ul>

The kbrd highlight
... or
 * For use to highlight a key press which is not part of a shortcut, with white background and bold, italicized text. Capitalize only the first letter when typing the text. For example, use it in a case like this:  Return or  to produce Return.
 * See the above shortcut span and template description for instances where that span/template should be used instead of the kbrd span/template

The button templates
... or }
 * For use to highlight an on-screen rectangular dialog button with plain text on a light gray background with a medium gray border. Only use the button span for buttons that actually have text on the button. Therefore usage with toolbars that have their own unique button images is not appropriate - use an image of the button instead.  For example, use the button span in a case like this:  Click the Export... button or Click the  button to produce Click the  button.


 * Use of other button templates
 * The following button templates can be used to highlight on-screen radio buttons, checkboxes and drop-down menus:


 * From the File Type drop-down menu, choose
 * From the File Type drop-down menu, choose
 * Note the usage of the DropdownMenu template: the actual selection made in the drop-down menu is highlighted, not the title of the menu.
 * From the File Type drop-down menu, choose
 * From the File Type drop-down menu, choose
 * Note the usage of the DropdownMenu template: the actual selection made in the drop-down menu is highlighted, not the title of the menu.
 * From the File Type drop-down menu, choose
 * From the File Type drop-down menu, choose
 * Note the usage of the DropdownMenu template: the actual selection made in the drop-down menu is highlighted, not the title of the menu.
 * From the File Type drop-down menu, choose
 * Note the usage of the DropdownMenu template: the actual selection made in the drop-down menu is highlighted, not the title of the menu.

Tables of Contents
In view of the disruption these cause to layout on reference pages, and given they don't really aid accessibility, we now force hide them on all such pages by adding.

Other Tables
Indentation

As with images, we usually prefer to indent inline tables. A colon can be added before a table written in Wiki syntax to left-indent the table by 1 em. However due to a Wiki bug, a colon before a table in HTML syntax writes <dl><dd> to the page source but does not close the <dl>, making the rest of the page indented. Workaround: use  margin-left:1em  in the table style declaration, instead of the colon. Adding <dl><dd> before the HTML table and </dl> after it works, but is strongly discouraged because it makes screen readers read out "list" when it isn't really a list.

Footnotes

User a superscript in a table underneath (to stop the text wrapping underneath the superscript). Example:

This can also be written using the footnote template:

Settings content
Images of an Audacity window or dialog should contain Audacity default settings which can be obtained by initializing Preferences.

Access keys
It was decided that images look better if access keys (underlines in buttons or in the text of controls that display in Windows and Linux) are not shown. This means accessing the menu with the mouse when grabbing the image, not using ALT or shortcuts to do so.

Placement
If images are nearly full screen width, they should be centered by piping "center" in the image link. Less wide images should be left-indented by preceding the image link with a single colon. Their left edge should then line up with the first word of bulleted text.

Size
All images should fit without scrolling in a maximized web browser window at 1024x768, unless it is impossible to otherwise display them satisfactorily. Ideally, smaller images should fit without scrolling at 800x600 too. While images can be scaled by adding a pipe, for example ''' ''', this will significantly degrade the image quality. If the image won't fit the Manual without scrolling at 1024x768, consider capturing it at a different screen resolution, or scaling it in an image editor rather than browser scaling.

<div id="small_inline">

Small inline images
Small inline images such as of toolbar buttons should not be wrapped in or preceded by punctuation such as colons or parentheses.

Clicking the image should not link to the image page. You can achieve this by adding a  link=  pipe in the image link for example  .

For "Getting Started" it is acceptable at author's discretion to repeat the image when the button name is repeated, otherwise confine the image to first use in the paragraph or section.

Hover/ALT Text
All images should carry alternative (ALT) text to facilitate readability by non-sighted or sight-impaired users employing screen readers. This text is also visible when hovering over the image with the mouse or if the image fails to load.

To include ALT text, add a pipe symbol " | " then the ALT text after the pipe, for example ''' '''

Note: The general received wisdom is: don't start the ALT text with "Image of".

Themes
Most images are of Windows 7 with basic theme unless noted otherwise, so it is preferable if new images of Windows 7 also have that theme. If a Windows 7 image is added with an "Aero" or non-default theme, point this out in the image text or hover text so that user does not think this image appears like this with Windows basic theme. Consider a Px to replace the image with basic theme when possible.

Drop Shadows
Bill 13Apr11:  I think we need to have a discussion on the use of drop shadows on images. I have been adding subtle drop shadows to track images (since they are not full windows, and I think they look better). I have not been putting drop shadows on full window images, nor on toolbars, comboboxes and other interface elements. Ed has started putting drop shadows on everything, and his drop shadow effect is very dark. So my take is that, for consistency, and before more images are updated, we need a policy on this.

Steve the Fiddle +1 for the lighter gray shadows. I also notice that the angle of the shadow appears to be different. I think that the shadow mostly below the image and a little to the sides looks OK and is similar to what I actually see on dialogue screens. I'm not sure exactly which elements should have drop shadow effects, but not combo boxes and similar interface elements.

Gale: Peter said on the Manual list that he does not like Ed's drop shadows. If we had them as Ed's Preferences dialogues were, we would have to do that for every real window like an effect dialog and the effect is I think far too gross. I think a policy of subtle drop shadow only for images that do not naturally have a sharply defined edge (with some latitude given to the image provider on what he does) worked OK and we should stick with it. Also see my comment in Talk:Warnings Preferences.

Bill: Ed doesn't like Ed's drop shadows either! When I started putting drop shadows on images I was working on the Edit Menu page. The track images on that page already had drop shadows on them and I tried to replicate the effect so that my new images would fit in. I liked the look and started doing it whenever I felt it worked. So +1 to "only for images that do not naturally have a sharply defined edge (with some latitude given to the image provider on what he does)".

Image Frames
We now don't use image frames in the Manual. They suggest (sometimes wrongly) that you can get at the essential page content by just reading the frames, often merely repeat the text, and can be too long for the ALT text they generate (ALT text should be about 12 words maximum).

Lists
This applies to both ordered and unordered lists:


 * The introductory text to a list has a colon at the end of it. We don't use a period, even if it's a complete sentence.
 * The first letter of each list item is in upper case.
 * We do not add punctuation at the end of list items, except we add a period if the item is a sentence, or if it is followed by a sentence.
 * In general, try to avoid mixing sentences and non-sentences in list items.

Reference section

 * The reference section should avoid tutorial exposition; it's kept brief, and links to tutorial sections as needed. (Should be viewed intelligently, so as to avoid shunting users around too much and avoiding creation of half-page "tutorials" for the sake of it which is a significant reason for our duplication problem).