Basics

Learn the basics of how to write good content.

Voice

Voice describes the contents mix of vocabulary, tone, point of view, and syntax which defines style.

This is one of the most important aspects of content writing. Strive to use active voice in your content — it's concise and easy to read. In active voice, the subject of the sentence performs the action.

Formula: Subject (person/thing acting) verb (the action) object (receives the action).

Passive voice

Passive voice is boring! It's long-winded laborious to read, not concise, and complicated to translate into other languages. Avoid boring your users — avoid using passive voice in your content. In passive voice, the subject receives the action.

If your sentence contains the following, it's likely passive:

Object comes before the subject. Example: "The information was updated by the customer".
Past tense verbs. Examples: "was added", "was created", and so on.
Forms of the verb "to be". Examples: "was", "is", "were", and so on.

Examples

Do (active)	Don't (passive)
The dog bit the person.	The person was bitten by the dog
Adds details to the product	Details were added to the product
Updates user information	User information was updated

Person and point of view

The term "person" refers to the point of view that is represented by a statement, and also helps determine which pronoun to use. Use second person when you're telling the user how to do something, or to do something. Use third person for everything else.

Second person

In second person, write as though you're speaking to the user. Second person often uses the personal pronoun "you", but sometimes the word "you" is implied. It supports a friendly, human tone and helps avoid passive voice by focusing the discussion on the user.

Where possible, avoid starting sentences with "you can". "can" is passive and makes the statement seem optional.

Examples
Use the collect feature to gather information on a specific metric.
To proceed, you must select a payment method.

Third person

Use third person to describe how something works. Third-person pronouns include: "it", "its", "they", "them", and "theirs". Don't use the third-person pronouns "he", "she", "him", or "her". For more information, see pronouns and gender.

Examples
The collect feature gathers information on a defined metric.
When the application is shutdown, documents are stored to disk.
An array is a data structure. It stores a collection of elements.

First-person plural

First-person plural uses the pronoun "we". This may sound as though you're speaking in a corporate voice and on behalf of a company. Where possible, avoid using "we".

Parallelism

Parallelism helps to make your content easier to read and localize. Use parallel structures to ensure that related content takes the same grammatical form. For example, all related items in a list are either a noun or a verb, not a mixture of both.

Example
Open a new file. Update the file details. Save the file.

Brevity

Use short concise content. Avoid using wordy-words or more words than are necessary to express an idea. Long-winded content increases the cognitive load on the user, complicates meaning, and creates a bad experience. It's important to be concise in all content, but this is especially important for: labels, buttons, headings, and error messages.

Do	Don't
A successful operation…	In the case of a successful operation…
Lately	As of late
More than/Over/Exceeding	In excess of
To	As a means of
Because	Due to the fact
To	In an effort to

Contractions

Use contractions to abbreviate words. This helps to create a casual and human tone. Avoid using contractions that sound awkward when you read the sentence out loud.

Do	Don't
Don't	Do not
Can't	Can not
Hasn't	Has not
You've	You have
You're	You are
It's	It is

Avoid Latin abbreviations

Avoid using Latin abbreviations. Although they are brief, they can be easily misinterpreted.

Do	Don't
And so on (Consider editing this term out — it's vague.)	etc.
That is	i.e
Using/Through	via
For example	e.g
Conversely/With the order changed	vice versa

Tense

Tense is the form of a verb that indicates when events or actions occur. Your verb choices can also indicate aspect, which expresses the completeness or effects of an action.

Content with mixed tense is difficult to read. The user may not be sure of when an event or action will occur, or when they should perform an action. It's also difficult for the author to keep track of mixed tenses, and to decide which is more appropriate for each sentence.

Where possible, write in present tense and avoid mixing tense.

Present tense

Strive to write in present tense. It makes your content much easier to reader and also more concise. Use present tense to describe events or actions that are true when the user reads them.

Do	Don't
Deletes an invoice item.	Invoice items will be deleted.
Invoices send at 10:15.	This invoice will be sent at 10:15.
Click the Invoices tab.	You will need to click the Invoices tab.

Future tense

Future tense describes events or actions that will be true at some point in-time after reading. Where possible, avoid using future tense.

Do	Don't
When you send an unsubscribe message, the server removes you from the mailing list.	When you send an unsubscribe message, the server would then remove you from the mailing list.

Gerunds

The gerund is a verb form ending in "-ing" which is used to form verb tenses. Avoid using gerunds, especially in headings. Gerunds create a passive tone and sentences that may be misinterpreted.

Do	Don't
Set up an app	Setting up an app
Get started	Getting started
Connect a device	Connecting a device
Edit information	Editing information

Spelling

Use US English in your content.

Examples of some differences between US and UK English:

US	UK
Canceled	Cancelled
Expiration	Expiry
Color	Colour
Center	Centre
learned	Learnt
License	Licence
Flavor	Flavour

Bold

Use bold text to emphasize static UI elements like menu items, buttons, headings, and labels.

Do	Don't
Go to the Settings page.	Go to the Settings page.