Consistency

Wording and punctuation

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

• 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.
• 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"
• File formats should be fully capitalized without preceding period (full stop), so:

"MP3", not "Mp3", "mp3" or ".mp3"

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).

• Hyphens: "right-click" and "double-click" not "right click" and "double click" ; "downward-pointing" not "downward pointing"; "drop-down" not dropdown.
• Internet: "e-mail" not "email"; "web site" not "website"
• Keyboard 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 <span class="key"></span> tags as described at Spans and Divs.
• Menu paths are formatted inside <span class="menu"></span> tags 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:

"resampling", not "re-sampling"

"sound card" not "soundcard"

• Units: "dB" not "db", "seconds" and "milliseconds" not "s" and "ms". There must always be a space between the value and the unit (for example, "10 dB" not "10dB").

GUI Elements

• "plug-ins", not "plugins" or "Plug-Ins"
• "selection region", not "selection area" because menus refer to "regions"
• "Timeline", not "ruler" or "horizontal ruler" or "time ruler"
• "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 '''''[[Glossary#log|logarithmic]]''''' scale.

Which gives:

This is a logarithmic scale.

-

Glossary link information:

'''''[[Glossary#link|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 straight forward. 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'.

Layout

Headers

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.

Note: Stick to one line of space before each of the different order headings. On the main Wiki we find two empty lines before h2 works well, but the best solution is to change the css to give a little more space above h2.

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.

The only exception to this is where the text in bold describes a menu item. In that case the text in bold is given verbatim, exactly as it is on the menu. However, even here the first word of the descriptive text should be capitalized.

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.

Still undecided:

• individual Menu pages: This was suggested:
  
  • At the top, use a table with an image of the menu to left and a description of the menu to right. Define the table as class="prettytable". This will give a table with blue headers without internal or external borders (the look will be tweaked later).
  • The name of each menu item should be exactly as it occurs in the image, and in bold, but without other punctuation. Add some brief text to give a quick idea of what the See Analyze Menu for an example.
  • Then write the detailed text, enclosing each menu item in second order tags e.g.
    == Open... ==

• However it has 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 brief text is another problem. Gale tried some alternative ideas at Help Menu, but this menu is short and almost anything would work here. Very likely the brief text idea is on the way out.

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

Spans and Divs

• Use of <div class="intro"> </div> tags

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 <note> div below if what you are highlighting is not at the top of the page. The color of this div may need tweaking?

• Use of <div class="note"></div> tags
  • 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.

• Use of <div class="alert"> </div> tags

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:

<div class="alert">Never press this button when you are recording!</div>

• Use of <span class="menu"> </span> tags

For use to highlight a sequence of menus, buttons or similar with gray background. For example, use it in a case like this:

<span class="menu">Edit > Select > All</span>

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 but we suggest bold enclosed inside quotes. This is done by prepending a double quote " followed by three apostrophes ', then appending three apostrophes followed by a double quote. Thus, "'''Preview'''" gives "Preview".

We have two similar styles for presenting menu items with links : File > Check Dependencies... which is written <span class="menu">[[File Menu#Check Dependencies...|File > Check Dependencies...]]</span> and File > Check Dependencies... which is written <span class="menu">[[File Menu|File]] > [[File Menu#Check Dependencies...|Check Dependencies...]]</span>

Note that in the first example, the entire span is a single link to the item's section on the File Menu page; the second example has File linked to the File Menu page and Check Dependencies... linked to it's section on the File Menu page.

Both are in use in the manual; we should pick one and stick with it. I propose using the first example as it seems less likely to confuse the reader.

• Gale: 25 Feb 11: Good point. I always use the two separate links IIRC and prefer that because a complete novice might be confused if forced to arrive at an anchor. Also the single link suggests there might only be one click action involved whereas there are two distinct click actions.

PS Please see It's vs Its.
Ed Thanks for pointing out that mistake, I know the proper form but still often get it wrong! In fact, the only way to change grammar is through common usage--personally, I think we should have only "it's" for both the possessive and the contraction--only thru (sic) common usage will it be changed <grin>!

• Peter: 28 Feb 11: I normally have a preference for a single link rather than the compound one. When directing user to use the "File>Import" command for example, I normally want to link them straight to the actual "import" section of the page. If thought necessary to direct then the the "File" menu itself I would prefer to reference it directly in the text. Personally I find the compound links more confusing overall.

• Use of <span class="key"> </span> tags

For use to highlight a keyboard shortcut with gray background and italicized text. For example, use it in a case like this:

<span class="key">CTRL + A</span>

Gale 25 Feb 11: I notice that I use <Key> for a key to be pressed that is not a shortcut but others use <span class="key">. The main wiki has a different template for key presses that are not shortcuts. We should be consistent, but I prefer not to use <span class="key"> for shortcuts. If so, maybe <Key> without bolding would be better? Example at Metadata Editor.

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 __NOTOC__ .

Other Tables

Footnotes

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

{|
|-
|valign="top"|<sup>(1)</sup> 
|The long and short jump times can be set in [[Playback Preferences]].
|}

Images

Settings content

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

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 [[File:Options.png|600px|mixing options]], 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.

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 grey 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.