Writing a Dev Center Article

Last updated 09 April 2020

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

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

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:

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:

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:

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:

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.