Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Dev Center
  • Heroku Dev Center Voice and Tone Guidelines

Heroku Dev Center Voice and Tone Guidelines

English — 日本語に切り替える

Last updated February 15, 2022

Table of Contents

  • Be Direct
  • Be Concise
  • Be Positive
  • Use the Second-Person Narrative
  • Use the Active Voice
  • Use the Present Tense
  • Additional Guidelines

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.

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.

Keep reading

  • Dev Center

Feedback

Log in to submit feedback.

Writing a Dev Center Article Writing a Dev Center Article

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences