Voice and tone

Devo's voice is how we communicate with users. When creating content it's important to consider not just what we say, but how we say it.  Although our voice is consistent throughout all of our documentation, its tone adapts to each situation as well as the reader's expectations. 

Devo's voice is clear, informative, and relaxed.  We use an informal style to write content that is both simple and instructive. Check this article for more information on keeping your writing and tone gender neutral.

Less is more

Short sentences are better. Remove superfluous words. Consider splitting up your sentence if it is filled with commas or parentheses.

Be human

Even though this is technical documentation, avoid sounding like a robot. Read your text out loud and ask yourself if this is something a human would say. Also keep in mind that not all readers are experts on the given topic.

Robotic: Invalid password.

Human: Your password must contain a mix of letters, numbers, and special characters.

Be present

Where possible, use the present tense and avoid using the past or future tense. This makes following procedures and instructions easier for readers and gives a sense of immediacy.

Contractions

Use contractions whenever possible: it’s, you're, we've, we’re, let’s, etc.

Be direct

This isn't creative writing, it's informative. Lead with important actions. The user wants to find information quickly. This allows the reader to scan the page for key words.

Most of the time, start each statement with a verb. Avoid using "you can" and "there is", "there are", "there were". 

Punctutation

Don't use periods on titles, headings, subheads, and items in a list that are three words or fewer.

Oxford comma

In a list of three or more items, include a comma before the conjunction.

Example
Avoid this: Android, iOS and Windows

Use this: Android, iOS, and Windows

Avoid spaces

Use only one space after periods, question marks, and colons—and no spaces around dashes.

Use simple English

Avoid Latin phrases when a common English phrase exists, such as for example in place of e.g.

Avoid non-English words or phrases.