Last updated February 15, 2022

This article contains the voice and tone guidelines for the Heroku Dev Center. If you’re writing or updating a Heroku Dev Center article, follow this guide to ensure a consistent reading experience for users.

Be Direct

Dev Center’s tone is factual and direct. Convey subject matter in a clear and confident manner.

Rephrase vague language such as “should”, “seems” or “probably”. Instead of:

It seems like every SSL reseller packs their certificates in a slightly different way with slightly different filenames.

Use:

SSL resellers use a variety of naming conventions when packaging certificates.

Focus on User Goals

Make sure that you create content for an actual use case.

Being factual means sharing just the facts. Introduce required conceptual information only when the user performs the related task. Unrelated concepts belong in a separate article. You can always link articles to each other.

Be Concise

Use as few words as possible. Write small blocks of text. Avoid long, complex sentences.

Contractions

Use contractions when possible.

Be Positive

Whenever possible, phrase sentences positively instead of negatively.

Instead of:

Don’t use a database with a plan smaller than standard-4 with Heroku Connect in production environments.

Reframe it in the positive:

Use a database with a standard-4 or larger plan with Heroku Connect in production environments.

Use the Second-Person Narrative

The second-person point of view uses “you” to address the reader. It works well in technical documentation because it focuses on the reader and enables you to use the imperative mood.

Use “you” instead of “I” or “we” (the first-person point of view) in Dev Center articles.

Instead of relating your personal experiences to the reader:

Based on our own experience managing remote assets, we created the foo gem so you can transparently upload your static assets to S3 on deploy.

Present concepts based on their own merits:

The foo gem enables you to upload static assets transparently at deploy time.

Use the Active Voice

Use active voice whenever possible. Be careful not to change the meaning of a sentence when rewording from passive to active voice.

Passive voice can be appropriate in some cases:

• When using active voice would create an awkward construction
• When the subject is unknown or not the focus of the sentence
• When you want to avoid blaming the user

Identify the real subject and switch from passive to active voice. Instead of:

The data is entered.

Use:

The user enters the data.

You can also replace the passive voice with the imperative. Instead of:

The name argument must be provided with this command.

Use:

Provide the name argument with this command.

Use the Present Tense

Use the present tense whenever possible. Instead of using the past tense:

This guide was created to describe the voice and tone of a well-written Dev Center article.

Use:

This guide describes the voice and tone of a well-written Dev Center article.

Similarly, use the present tense instead of the future tense. Instead of:

After you log in, the registration dialog will appear.

Use:

After you log in, the registration dialog appears.

Additional Guidelines

This article contains the voice and tone guidelines for the Heroku Dev Center. When writing an article, you must also adhere to the Style and Content Guidelines. For more info, see Writing a Dev Center Article.