Skip to main content

Golden rules

We recommend that you follow a few simple - yet important - rules when contributing to the Unraid Docs. These are intended to help every contributor write in a similar style, for a global audience of Unraid OS users.

Good documentation is informative, simple, concise, and clear. It delivers what the audience needs to know about a subject without adding fluff.

Rule #1 KISS - Keep It Super Simple​

Strip away complex language and go straight to the point. Make text easily understandable by putting yourself in the audience's place. You never know who’s reading your document or what their level of English is.

Keep sentences short as the help reading comprehension and information retention. Of course, you won't always be able to do this, especially when describing procedures or writing about the command line, but outside that, be direct.

Rule #2 Use plain (American) English​

We write in American English, so avoid all the usual conflicts of British English vs American English. Wikipedia has a comprehensive list of differences.

Rule #3 Avoid using idioms and loanwords​

Idioms are expressions that have a figurative meaning and are used to give emphasis and color to your writing. They are often specific to a language and can be difficult for non-native speakers to understand because their meanings are not directly derived from the individual words.

Translators may find it difficult to translate the text to another language.

The same applies to loanwords. Sometimes, to make a point, we may feel the need to use a loanword that may cause confusion to non-native English speakers.

Rule #4 Be consistent​

A consistent writing style involves maintaining uniformity in various elements of writing across a piece of work or a collection of works. This consistency helps ensure clarity, professionalism, and readability. Key aspects of a consistent writing style include:

  • Tone and voice - We are fairly informal in our docs, and that comes across in the writing. We don't use slang and jargon to avoid confusing readers.
  • Grammar and syntax - Try and follow the same sentence structures and grammatical rules every time.
  • Formatting - Keep headings and paragraph text consistent.
  • Spelling and capitalization - We prefer sentence case for titles, and we rarely use all-caps to illustrate a point.

Rule #5 Know your audience​

Always put yourself in the place of the reader. Think of who you're writing for, the tone and voice, and terminology you use. Consider the complexity of the language you are using. Writing for an Unraid user who has no programming or command line experience is very different than writing for a developer.

Rule #6 Limit the use of conjunctive adverbs​

Whether it's the way you learned English, or simply your style of writing, conjunctive adverbs can be mistranslated or misunderstood. They also sound a bit archaic, so it's best to avoid them. You're not writing a legal document, you're writing for the widest audience possible.

Some common conjunctive adverb types you should try to limit:

  • Addition: besides, furthermore, moreover
  • Contrast: however, nevertheless, nonetheless, still
  • Cause and Effect: therefore, thus, consequently, hence
  • Time: finally, subsequently, meanwhile
  • Comparison: similarly, likewise

Rule #7 Use the active voice​

The active voice is a grammatical structure in which the subject of a sentence performs the action expressed by the verb. It contrasts with the passive voice, where the subject is acted upon by the verb.

In the active voice a sentence follows a straightforward subject-verb-object (SVO) order and results in clearer, more direct, and more engaging sentences.

Rule #8 Be unambiguous​

When writing about Unraid, never leave room for doubt. For example, if you are writing a procedure, say what has to be done, without leaving room for the user to question what options they have. If there are multiple options, you should describe the effect of each.

For example, don't write "You can select" when just "Select" is clear enough.

Rule #9 Check your writing​

We won’t tell you to check Merriam-Webster’s Collegiate Dictionary, or the Chicago Manual of Style, but it’s always a good thing to read your text back to yourself to see if it makes sense and your point is clear enough. This minor exercise will help identify any issues with your writing.