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"

• Audacity when used as the proper name of our editor must be capitalized i.e. "Audacity", not "audacity".
• 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).

• menu paths are indicated by " > " e.g. "File > Export..."
• 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. Numbers less than 10 are written out as text ("five tracks" not "5 tracks")
• quotes are inside double quotes, not single, so " ", not ' '
• shortcuts: 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"
• 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 bold italic, but 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#Logarithmic|logarithmic]]''''' scale.

Which gives:

This is a logarithmic scale.

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.

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.

• individual Menu pages:
  • 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 headers against a blue background, 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. See File Menu for an example.
  • Then write the detailed text, enclosing each menu item in second order tags e.g.
    == Open... ==

Still undecided:

Toolbars. See the competitors at:

• Edit Toolbar, Tools Toolbar and Control Toolbar - and the comments thereon.

Use of <div class="note"></div> tags

• The current 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.

• (another use, under discussion) It's suggested that where detailed text is already brief, and so only a sentence or two of summary "quick text" above it is needed, enclose the quick text in these tags to make it look better. Examples are at Control Toolbar (quick text very short) and Label Tracks (longer text, maybe not so clear a case, but being consistent may over-ride that). This idea could possibly be extended to provide a few "introductory" sentences on most non-menu pages, or most non-Reference pages. Introductions in a colored panel are successfully used on the main Wiki. If this is thought a good idea, we should probably create a special div with its own color for this purpose.

Like the idea, if we use a new div name. How about "quicktext"? I would suggest that we try to be strict about using it only for the first paragraph of text on the page (Label Tracks use is OK, more paragraphs wouldn't be, methinks).

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

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