Be active and present

Using active voice and present tense helps readers understand actions and expectations as they navigate the content.

Strive for active voice and present tense in your documentation. Writing in active voice allows readers to place themselves as the subject in the documentation, and present tense tells readers what they can expect as they work through the content.

Note: While using passive voice and future tense is sometimes appropriate in documentation, keep your audience in mind by writing in plain language and centering your writing around the user as much as possible. For more information, see Use plain language.

Active voice

Active voice makes content clear by indicating who or what performs the action, even when the subject is implied. Minimize passive voice in your writing.

Review the following table for examples rewritten to use active voice:

"" Do this "" Don't do this
Select Print to print the document. When the Print button is selected, the document is printed.
The forwarder sends data to the receiver. Data is sent to the receiver.

When is it okay to use passive voice?

Write in passive voice carefully and sparingly. The following examples describe situations where you might choose to use passive voice instead of active voice:

  • When you want to avoid placing blame on the user, such as in an error message.
  • When defining the actor in the sentence is irrelevant or awkward.

Present tense

Present tense allows readers to experience the documentation while they read it. Minimize the use of past tense or future tense in your writing.

Review the following table for examples rewritten to use present tense:

"" Do this "" Don't do this
The summary statistics continue to calculate allowed items, but the items don't appear in the dashboard. The tool processes all apps before they are published to Splunkbase.
All apps are processed through the tool before they are published to Splunkbase. The tool will now process all apps before being published to Splunkbase.
After the search is completed, the table updates automatically. After the search was completed, the table updated automatically.

When is it okay to use future tense?

Write in future tense carefully and sparingly. Do not use future tense if you can rewrite the sentence to use present tense instead. In general, strive to keep documentation timeless, and avoid writing about time-sensitive information that might become irrelevant in the near future. For more information, see the information about timelessness in Use plain language.

The following examples describe situations where you might choose to use future tense:

  • In tutorial content, when describing what the reader will achieve during the tutorial part.
  • In deprecation or end-of-life statements for a product.