Style and Tone
While contributing to Jamulus or the website, you should also keep style and tone in mind. Have a look at the following principles:
Keep it concise and specific.
Avoid long-winded phrases and overly stylised language. Start simple, expand to details later, if at all (“inverted pyramid” style).
Be direct, but not demanding.
Let users know what they need to do, but don’t order them around.
Know your audience.
Jamulus has users of varying skill levels ranging from complete beginner to audio professional. When writing content, identify your audience and make sure to use terms that they would understand.
Avoid using slang and euphemisms.
Jamulus is used around the world and translated in five languages (possibly more!). Use plain english to provide users and translators an easier understanding of our content.
Give solutions first.
Resist the temptation to say why something happens before offering a solution for it. Users are not engineers and do not care about causes. If you want to give reasons, put them in a footnote, but consider not doing so at all.
We use British English.
“Colour”, “minimise”, “centre”
Tone (Keep it Light)
Informal English is preferred (eg “haven’t” not “have not”. “Try to” not “Please attempt to”.
Try not to sound like a robot. Write conversationally, as if you were talking to a person.
Capitalisation and references
Headings use sentence case “This is a heading” unless delineated (“Look - This is a heading”).
Nouns use lower case unless they have a formal definition in this style guide (eg “Directory”, “Fader”). The only exception to this is the word “person” or “people” which can remain in lower case.
Refer to UI labels in inverted commas (eg “click on the “mute” button)
“Sound card” (not “audio device” or “sound device”) to refer to on-board audio interfaces only. “Your sound card will be listed by default”, “Most computers have compatible sound cards”.
“Audio interface” to refer to external sound cards. “If your audio interface comes with a driver”, “Your audio interface may be set to ‘monitor’”
“Sound hardware” refers generically to both internal and external audio cards. “Your sound hardware will introduce some latency”, “Most sound hardware can be used”.
“macOS” (not “Mac”, or “MacOS”)
Jamulus is “Free and Open Source (FOSS)” (not “free software” or “open source”)
“Channel” The audio signal as part of a mix. “Mute a channel”, “Maximum number of channels” (not “Mute a person”, “Group channels together”).
“Fader” The UI that controls a channel. “Each fader has a mute button”, “The person’s fader” ,“Group faders together” (not “The person’s channel” or “Mute a Fader”, “Slider” or “Volume control”)
“Person” A human connected to a server (may be on multiple channels). “People on the server”, “People who have muted themselves” (not “Musicians”, “Maximum people on the server”)
“Server” The general term for the machine that a client connects to. Not to be confused with “Directory”.
“Directory” The general term for a server that a client uses to get its list of public servers from. Use the term “Directory server” cautiously - it may be confusing in the presence of “Server”.
We use the following abbreviations:
Kbit/s; Mbit/s; KByte/s; MByte/s.
Values followed by units such as
GHz etc. should be separated by a space; e.g. “20 ms” and “1 GHz” not “20ms” and “1GHz”.
It is very important to thoroughly proofread content before submitting it, as any corrections made later have a knock-on effect on translations.