Writing a Dev Center Article

Last updated 10 August 2017

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 certs in a slightly different way with slightly different filenames.

Use:

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

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.

Structure

Article title

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

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

Graphics

Images succinctly convey hard to understand concepts or step explanations and are great tools to provide a visual break from the monotony of reading a large block of text. Use them to emphasize important concepts and support the larger article structure.

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

All images (and external assets in general) should be referenced via https to ensure readers securely accessing the Dev Center aren’t presented with warnings.

Step verification

If the article is a tutorial the author is responsible for executing the steps in the sequence mandated by the article. Utilizing a fresh environment will ensure symmetry between the writer and readers’ environments.

Articles with sample applications should include complete instructions for running the application in a local environment and any required system dependencies.

Minimize introduction of new tools

As part of creating technical Dev Center content it may be necessary to introduce new tooling, libraries and frameworks to efficiently solve a particular class of problems. Introduce new tools with great forethought.

Build the work-flow on top of easily understood and widely documented technologies. If unavoidable, consider structuring the content into multiple articles to establish the benefit of a new tool independently. Only if its presence speaks directly to the solving of the core problem should a new tool be presented within the article.

Library/framework configuration

Applications running on Heroku should not store configuration settings within the code-base as files. To maintain consistency with the Heroku approach to application configuration all referenced frameworks should read settings from environment-based configuration variables.

This presents a consistent face to the tenet of separation of config from code and reinforces the clean contract between the platform and the application.

Supporting applications

A deployable reference application is a great way to convey the totality of a particular approach and allows the writer to focus on the core steps associated with the broader solution being presented.

If such a companion application exists 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 will produce an obvious reference to the app early in the article and present 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 add-on, deployment and scaling CLI commands.

Formatting

Markdown formatting

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

## Section header

Here is some text, and a [link](http://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

A table of contents will automatically be generated by the Dev Center keyed off of top level H2 (##) elements.

The following header structure will result in a TOC with Header 1 and Header 2 elements.

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

Inline notes

Notices or warnings of destructive or irreversible behavior should be displayed inline to reinforce their importance. Warnings are specified with the warning class.

>warning
>This is a warning message

And are rendered as:

Similarly, notices of a less destructive nature that are still central to the reader’s comprehension of the topic are denoted by the note class:

>note
>This is an important notice

and are rendered as:

Callouts provide a mechanism to display relevant but non critical-path information, and are created by beginning each line of the called out text with a > character, and by having a line at the start with the word callout:

>callout
>Called out content

Links

Links to other Dev Center articles

Link to other Dev Center articles by using that article’s stub. 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.

Internal links to sections of the current article

Link to sections within the same Dev Center article by referencing the section’s stub with a hash symbol in front of it. For example, to link to the “Formatting” section of this article, you would do this:

Here is a link to the [Formatting](#formatting) section of this article.

Result:

Here is a link to the Formatting section of this article.

External links

Use the full URL when you are linking to external sites.

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

Result:

Here is a link to the Twelve-Factor App.

Code

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

Fenced code blocks

Code blocks should be clearly associated with the containing file for clarity with users that are unfamiliar with file structure of the framework being used.

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

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

Is rendered as:

puts "hello world"

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

Inline code

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

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 cedar-14
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 cedar-14
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. Output should be limited to the relevant portions so as not to overwhelm the reader and obscure the topically supportive nature of the example.

Spelling

Dictionary

For spelling questions, refer to dictionary.reference.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

These words have multiple spellings or are ambiguous. Here is how we spell 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
• 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.
• Mac OS X
• 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, sign-up: 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: Not utilise. Use our reference dictionary to determine the most common American spelling of words. Utilize is a synonym for use and if appropriate, say “use” instead.
• 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 our reference 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 our 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 CLI
• Heroku Connect
• Heroku Dev Center
• Heroku Elements Marketplace
• Heroku Enterprise
• Heroku Kafka
• Heroku Platform
• Heroku Postgres
• Heroku Private Spaces
• Heroku Redis

If it is obvious from the 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.