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 guidelines.
Note: It is very important to thoroughly proofread content before submitting it, as any corrections made later have a knock-on effect on translations.
Table of contents
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 (eg “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”, “Group channels together” (not “Mute a person” because one person might be using multiple channels).
“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”, not “Slider” or “Volume control”)
“Person” A human connected to a server (may be on multiple channels). We might say “People on the server”, or “People who have muted themselves”, rather than Musicians or Channels.
“Country/Region” Keep in mind that some areas of the world have a controversial (political) status. If possible, be generic and remain neutral. Instead of just saying country, use Country/Region or Location.
“Client” When capitalised, this means an instance of Jamulus running in client mode, used to connect to Jamulus Servers.
“Server” When capitalized, refers to an instance of Jamulus running in server mode. When lowercase as server, this refers to the computer that runs the Server (e.g. “A Server running on an AWS server”). Not to be confused with Directory.
“Directory” The term for a type of Server that a Client uses to get a list of Servers from. Avoid the use of the term Directory Server because it may be confusing in the presence of Server on its own.
“Registration” When a Server is configured in Registered mode, it will be listed when successfully registered by a Directory. Note that if a Directory is full, a Registered Server will not be listed because it has not been successfully registered. Note in this case we prefer to say, “Register with a Directory”.
“Server List” This is the list of Servers maintained by a Directory. A Server registers with a Directory to be listed in that Directory’s server list.
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”.