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 the Play Framework
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku 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)
    • 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
  • Extending Heroku
  • Dev Center
  • Writing a Dev Center Article

Writing a Dev Center Article

English — 日本語に切り替える

Last updated 20 January 2021

Table of Contents

  • Style
  • Grammar
  • Structure
  • Content guidelines
  • Formatting
  • Spelling
  • Example names

Nearly all Dev Center articles are written and maintained by either Heroku team members or add-on providers. This article is provided publicly in case it is helpful in establishing conventions for other documentation projects.

If you are writing or updating a Heroku Dev Center article, read this guide first to learn about the recommended tone, style, and structure of Dev Center content. This helps ensure a consistent reading experience for Heroku customers.

Style

Factual tone

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

Avoid using vague language such as “it 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.

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. Avoid using “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.

Present tense

Use the present tense whenever possible. Phrases such as “was created” indicate unnecessary use of the past tense. Instead of:

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

Use:

This guide describes the characteristics of a well-written Dev Center article.

Similarly, avoid unnecessary use of the future tense. Instead of:

After you log in, the registration dialog will appear.

Use:

After you log in, the registration dialog appears.

Inclusion

Whenever you use pronouns to refer to an individual that is not the reader, use “they/them/their” instead of “he/him/his” or “she/her/her”. You can sometimes simplify a sentence by rewriting it to omit pronouns entirely.

Whenever you create a screenshot or sample data that lists multiple hypothetical users or other individuals, include a diverse array of identities.

Grammar

Structure

Article title

An article’s title should describe the article’s topic plainly and concisely while using title casing:

Connecting to Relational Databases on Heroku with Java

A clear, unambiguous title helps ensure that readers identify the content that is most applicable to them.

Article introduction

Begin the article with a short overview of its contents. For example, this is the introduction from this very article:

If you are writing or updating a Heroku Dev Center article, read this guide first to learn about the recommended tone, style, and structure of Dev Center content. This helps ensure a consistent reading experience for Heroku customers.

Section titles

Use sentence casing for all section titles. For example, use:

This is a sentence-case section title

Instead of:

This is Not a Sentence-Case Section Title

 

Use the H2 header (##) for your article’s top-level sections. Dev Center parses these titles to construct the article’s table of contents. Do not use H1 headers (#) in your article.

Ordering content

If you are creating a tutorial that a reader follows along with, present steps in the order in which the reader should complete them.

If you are creating a conceptual article that describes a particular technology, describe the technology’s most universally applicable concepts before introducing advanced or obscure use cases.

Break up large top-level sections with subheaders (H3, H4, etc.) to improve readability and scannability.

Content guidelines

Verify all tutorial steps

If your article is a tutorial, you are responsible for performing the steps in the tutorial to ensure that it can be completed as written. Whenever possible, use a fresh development environment to do so.

Tutorials with associated sample applications should include complete instructions for running the application in a local environment, along with any required system dependencies. If the sample is hosted on GitHub, this information can live in the repo’s README, but the article should indicate this.

Introduce new tools only when necessary

A Dev Center article should require the use of a new third-party tool, library, or framework only if using widely supported default technologies is meaningfully less effective.

When introducing a new technology is indeed appropriate, consider creating an article that establishes the benefit of the technology to the Heroku platform.

Include deployable example applications when possible

A deployable reference application is a great way to convey the totality of a particular approach. This allows the article to focus more on the core steps associated with implementing the broader solution.

If your article includes a companion application, provide the following note after the article introduction:

>note
>Source for this article's [reference application](https://github.com/xyz) is available on
>GitHub and can be seen running at
>[https://example.herokuapp.com/](https://example.herokuapp.com/)

This provides an obvious reference to the app early in the article and presents users with the option to go directly to deploying.

The GitHub project should contain README instructions for running the application both locally and on Heroku using standard CLI commands.

Use abstract secrets rather than real ones

Some articles will require secrets, such as database connection strings or AWS S3 keys. For these cases, create abstract strings that show the form of the secret, rather than sharing an actual secret.

For example, a Heroku Postgres connection string should be:

postgres://user:password@ec2-1-2-3.compute-1.amazonaws.com:5432/databasename

Formatting

Articles are written in GitHub flavored markdown. Here is a brief syntax example:

## Section header

Here is some text, and a [link](https://heroku.com/).

![A descriptive image title](https://example.com/test.png)

### Sub header

* Bullet 1
* Bullet 2

And some output from a command:

```term
$ echo hi
hi
```

Now some code:

```ruby
puts "hello"
```

And a table:

|  A  |  B  |
| --- | --- |
|  1  |  2  |
|  3  |  4  |

Table of contents

Dev Center automatically generates an article’s table of contents from its h2 (## in markdown) elements.

The following set of headers results in a TOC that includes Header 1 and Header 2:

## Header 1
### Header 1.1
## Header 2

Ensure that your article’s top-level headers provide an accurate outline of the article’s content.

Graphics

Images succinctly convey hard-to-understand concepts and provide a visual break from large blocks of text. Use them to emphasize important concepts and support the larger article structure:

![Image title](https://s3.amazonaws.com/bucket/image.jpg)

Styled notices

Dev Center supports three specially styled notices:

  • warning
  • note
  • callout

Use the warning notice to advise the reader when a particular action is destructive or irreversible:

>warning
>This is a warning message

This snippet is rendered as:

This is a warning message

Use the note notice to highlight information that is critical to the reader’s comprehension of a topic, but not dangerous:

>note
>This is an important notice

This is rendered as:

This is an important notice

Use the callout notice to present information that is relevant to the topic, but not critical to the reader’s comprehension:

>callout
>Called out content

This is rendered as:

Called out content

Links

Linking to other Dev Center articles

You can link to other Dev Center articles by specifying only the article’s slug (the final component of its URL). Here’s an example of how to link to the Dynos and the Dyno Manager article:

The [dyno manager](dynos) is responsible for keeping dynos running.

Result:

The dyno manager is responsible for keeping dynos running.

Linking to a section of the current article

You can link to headers within the same Dev Center article like so:

Here is a link to the [content guidelines](#content-guidelines) section of this article.

Result:

Here is a link to the content guidelines section of this article.

Linking to external sites

When you link to an external site, use its full URL:

Here is a link to the [Twelve-Factor App](https://12factor.net/).

Result:

Here is a link to the Twelve-Factor App.

Code

As you’d expect, code is a big part of Dev Center documentation. The Dev Center supports syntax highlighting for all languages supported on Heroku.

The first line of a fenced code block should begin with three back ticks ``` and an optional language identifier:

```ruby
puts "hello world"
```

This is rendered as:

puts "hello world"

The following are the language identifiers for major languages on Heroku:

Language Identifier
Ruby ruby
Node.js / JavaScript javascript
Python python
Java java
Scala scala
Clojure clojure
Objective-C c
PHP php
Go go

Terminal commands

Terminal commands and output should use the term code block identifier. Precede terminal commands with a $ prompt indicator.


```term
$ heroku create
Creating blooming-water-4431... done, stack is heroku-18
http://blooming-water-4431.herokuapp.com/ | git@heroku.com:blooming-water-4431.git
Git remote heroku added
```

Is rendered as:

$ heroku create
Creating blooming-water-4431... done, stack is heroku-18
http://blooming-water-4431.herokuapp.com/ | git@heroku.com:blooming-water-4431.git
Git remote heroku added

Be sure to show sample output from commands to provide context and successful execution expectations. To improve clarity, show only portions of output that are relevant to the reader’s understanding of the command.

Heroku CLI commands

Many Heroku CLI commands support the --app option, which specifies the Heroku app to run the command against. When you show a Heroku CLI command in a code block, always include this option if the command supports it:

$ heroku config --app your-app-name

The app’s name should be your-app-name unless the article already uses another particular app name for illustrative purposes.

Inline code

Inline filenames, commands, and code should be surrounded by backticks. This ensures that `file.rb` is rendered as file.rb. Command-line commands, when shown inline, should not be preceded by a prompt symbol.

References to a user interface

Some Dev Center articles refer to a user interface, particularly those that involve Dashboard, Data or Connect. Here is an example:

To see the add-ons provisioned and attached to an application, visit Heroku Dashboard and click on the name of the app or click the Resources tab when viewing an app.

When writing about a user interface element, place the name of the UI component between ***` and `***.

In the above example, we wrote:

**`Resources`**

Do this for consistency, as well as to ensure that those elements are not translated into other languages.

Spelling

Dictionary

For spelling questions, refer to dictionary.com, which is based on the Random House Unabridged Dictionary.

The Salesforce Style Guide contains spelling guidelines for numbers and spelling guidelines for compound words.

Word list

The following words have multiple spellings or are ambiguous. Here is how Dev Center spells them:

  • add-ons: Not addons. When referring to an instance or a service, use lowercase (e.g., installing an add-on). When referring to our product, capitalize it (e.g., Heroku Add-ons, Add-ons Marketplace).
  • back-end: “The back-end is written in Java.”
  • canceled
  • CTRL+C: Use a plus sign, as in CTRL+C, to indicate key combinations.
  • cURL
  • Database as a Service (DBaaS): Hyphenate it only when it is used as an adjective.
  • Dev Center: (not Devcenter).
  • DevOps
  • distribution: When referring to a Linux distribution, use distribution instead of distro.
  • e-commerce: In headings with title-style capitalization, use E-Commerce. At the beginning of a sentence, use E-commerce.
  • email
  • front-end: “The front-end is written in Java.”
  • I/O: When referring to input/output, use I/O instead of IO.
  • IoT: The Internet of Things
  • JAR file: (not Jar file). Short for Java Archive.
  • login, log in: “Login” is a noun and “log in” is a verb.
  • macOS
  • Platform as a Service (PaaS): Hyphenate it only when it is used as an adjective. For example, Heroku is a Platform-as-a-Service vendor.
  • setup, set up: “Setup” is a noun or an adjective. “Set up” is a verb phrase. Example: After you set up your portal, your setup is complete.
  • sign up, signup: “Sign up” is a verb. “Sign-up” is an adjective or noun. Don’t use signup.
  • single sign-on: Hyphenate sign-on when referring to the single sign-on feature.
  • third party, third-party: Do not write 3rd party. Third party is a noun, third-party is an adjective. Examples: The software came from a third party. Third-party software.
  • unidle: (not un-idle).
  • Unix: Capitalize the first letter. Only use all-caps (UNIX) for the trademark.
  • URL
  • utilize: Avoid in favor of use.
  • webhook: (not web hook or web-hook).
  • web server: (not webserver).

Capitalization

Section titles within Dev Center articles use sentence casing. For example, ## My section title instead of ## My Section Title.

Use the dictionary to determine proper capitalization, and refer to this summary of capitalization rules in the Salesforce Style Guide.

Trademarks, brand names, and feature names

Capitalize “Heroku”. When referring to the URL, use “heroku.com”.

Capitalize product brand names to set trademarks apart from other words. Here are some examples:

  • Heroku Add-ons
  • Heroku Buildpacks
  • Heroku Buttons
  • Heroku CI
  • Heroku CLI
  • Heroku Connect
  • Heroku Dev Center
  • Heroku Elements Marketplace
  • Heroku Enterprise
  • Heroku Pipelines
  • Heroku Postgres
  • Heroku Private Spaces
  • Heroku Redis

If it is obvious from context that a product or feature is from Heroku, it is acceptable to omit “Heroku”.

Capitalize feature names only if they are brand names. Sometimes, it may be appropriate to capitalize a feature name that is not a brand name if there is a marketing campaign around it.

When referring to trademarks that are owned by other companies, follow their trademark guidelines.

Example names

When naming apps, try to use example as the name of the application, leading to a Heroku hostname of example.herokuapp.com. The app at https://example.herokuapp.com makes it clear that the reader is viewing an example.

When naming a domain, try to use www.example.com as an example domain name.

Keep reading

  • Dev Center

Feedback

Log in to submit feedback.

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