Consistency

Wording

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"

• 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: "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

• "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.

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 particular families is still being discussed.

Currently we have decided on this scheme for pages describing the 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.

Other families being considered are Toolbars and Menus. Competing looks include

• Edit Toolbar, Tools Toolbar and Control Toolbar - see the comments thereon.
• File_Menu vs Track_Drop-Down_Menu

I'm betting File Menu will win. 1) It will be less work to make it screen reader accessible. 2) It's more space efficient without the separate table column for the name of the item, so the quick text won't spread so far down the page - Gale

Agree. - James

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.