Heroku Dev Center Voice and Tone Guidelines
Last updated September 27, 2021
Table of Contents
Heroku team members and add-on providers write and maintain Dev Center articles. Non-Dev Center contributors can use this article as a reference for establishing conventions for their own documentation projects.
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.
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.
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.
Use as few words as possible. Write small blocks of text. Avoid long, complex sentences.
Use contractions when possible.
Whenever possible, phrase sentences positively instead of negatively.
Don’t use a database with a plan smaller than
standard-4with Heroku Connect in production environments.
Reframe it in the positive:
Use a database with a
standard-4or 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
foogem so you can transparently upload your static assets to S3 on deploy.
Present concepts based on their own merits:
foogem 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.
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.
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.
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.
After you log in, the registration dialog appears.
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.