Consistency
Contents
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"
- 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.
Caps
Is it MP3, Mp3, mp3 or .mp3? WAV, Wav, wav or .wav? "MP3 player", ".mp3 format"? I ask because we have both in the quicktext on File_Menu
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
Agree. - James
For all families, it's suggested that where detailed text is brief, and so only a sentence or two of summary "quick text" above it is needed, enclose the text in <div class="note"> </div>tags to make it look better.
Please give a link to an example so I can see and comment.
Use of <div class="note"></div>
- We're currently using notes primarily as 'tips', i.e. extra pieces of information which you don't have to know, which may be of particular interest to someone who already knows 90% of what has been written and is just skimming.
- Another (and in my view less good) use of notes is as a way to highlight information, just to break up the text a bit.
I think we're doing fine on this at the moment, but it could be worth deciding a specific policy.
