Heroku Dev Center Style Guidelines
Last updated September 28, 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 style 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 Markdown Overview
Dev Center articles use GitHub flavored markdown. Here’s a brief syntax example:
## Section header Use the H2 header (`##`) for your article's top-level sections. Dev Center parses these titles to construct the article's table of contents. **Don’t use H1 headers (`#`) in your article.** Here’s some more text, and a [link](https://heroku.com/). ![A descriptive title (required for images)](https://example.com/test.png) ### Subheader Here’s an unordered list: * 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 | > note > You can also include [styled notices](#styled-notices) like this one.
Only bold text when used with backticks to reference UI elements. Use italics instead for emphasis.
Use title capitalization for all titles and headings. For example, use:
Heroku Postgres Maintenance Windows
Heroku Postgres maintenance windows
As you’d expect, code is a significant part of Dev Center documentation. The Dev Center supports syntax highlighting for all languages supported on Heroku.
Begin the first line of a fenced code block with three back ticks
``` and an optional language identifier:
```ruby puts "hello world" ```
This snippet renders as:
puts "hello world"
The following are the language identifiers for major languages on Heroku:
term code block identifier for terminal commands and output. 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/ | email@example.com:blooming-water-4431.git Git remote heroku added ```
This snippet renders as:
$ heroku create Creating blooming-water-4431... done, stack is heroku-18 http://blooming-water-4431.herokuapp.com/ | firstname.lastname@example.org: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 example-app
example-app as the app’s name unless the article already uses another particular app name for illustrative purposes.
Surround inline filenames, commands, and code with backticks. This formatting ensures that `file.rb` renders as
Don’t precede command-line commands by a prompt symbol when shown inline.
Heroku App Names
When naming apps, use
example-app as the name of the application, leading to a Heroku hostname of
example-app.herokuapp.com. The app at https://example-app.herokuapp.com makes it clear that the reader is viewing an example.
When naming a domain, use
www.example.com as an example domain name.
When demonstrating a command with an ID, use angle brackets (
<id>) to replace the ID.
Some articles require secrets, such as database connection strings or AWS S3 keys.
Create an abstract string that shows the form of the secret, rather than sharing an actual secret. For example:
In other cases, using a fake secret instead of an abstract string is clearer for the reader. For example, a fake bearer token is shown here instead of an abstract string so the user can see its format better:
curl -X POST https://hc-central.heroku.com/auth/example-app \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"
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.
Most graphics are self-explanatory. If your image requires a description, describe it on a new line before the image instead of adding a caption below it. You can add images in Markdown like this:
Some text description of this image: ![Image title](https://s3.amazonaws.com/bucket/image.jpg)
Always include an image title within the
Follow these steps when taking screenshots for your article.
Set up your screenshot using “real” looking data. Resize your browser window to 1024 x 768 or smaller. Minimize unused space and try to omit anything that’s likely to become outdated later. Take the screenshot. Add callouts if needed. Add a 1-pt black border. Adjust the image to meet these guidelines: DPI: 200 Width in pixels: 800 px maximum. Width in inches: 4"
If a user must complete steps in a particular order, number them. Use complete sentences with proper punctuation.
For tasks where most steps are 1-2 sentences, create a numbered list, such as:
- Click the
Settingstab in the Heroku Connect dashboard.
Exportin the confirmation window to download the file.
See References to the User Interface for notes on formatting UI elements for your instructions.
Use italics sparingly for emphasis. You can make text italic by wrapping them in
_. For example,
*Text to italicize.*
Text to italicize.
Link to Other Dev Center Articles
Link to other Dev Center articles by specifying the article’s slug (the final component of its URL). Here’s how to link to the Dynos and the Dyno Manager article:
The [dyno manager](dynos) is responsible for keeping dynos running.
The dyno manager is responsible for keeping dynos running.
Link to a Section Within the Same Article
Link to headers within the same Dev Center article like so:
Here’s a link to the [content guidelines](#content-guidelines) section of this article.
Here’s a link to the code snippets section of this article.
Link to External Sites
When you link to an external site, use its full URL:
Here’s a link to the [Twelve-Factor App](https://12factor.net/).
Here’s a link to the Twelve-Factor App.
Use ordered lists for instruction steps, unless the steps are too lengthy.
Use unordered lists sparingly. Avoid nesting bullet points.
Introduce a list with the beginning of a sentence followed by a colon. If the introduction is a complete sentence, end it with a period.
Capitalize the initial word of each line item, whether it’s a fragment or a full sentence. End sentences with periods:
For fragments, omit the period:
The best practices in this article assume that you have: * Node.js and npm installed * An existing Node.js app * A free Heroku account * The Heroku CLI
References to the User Interface
Some Dev Center articles refer to a user interface, particularly ones that involve Dashboard, Data, or Connect. Here’s an example:
To see the add-ons provisioned and attached to an application, visit the Heroku Dashboard. Click the name of the app or click the
Resourcestab when viewing an app.
When writing about a user interface element, place the name of the UI component between
The formatting for the previous example looks like:
Use this formatting for consistency and to ensure that those elements aren’t translated into other languages.
Use the H2 header (
##) for your article’s top-level sections. Dev Center parses these titles to construct the article’s table of contents. Don’t use H1 headers (
#) in your article.
Dev Center supports three specially styled notices:
warning notice to advise the reader when a particular action is destructive or irreversible:
>warning >This message is a warning.
This snippet renders as:
This message is a warning.
note notice to highlight information that is critical to the reader’s comprehension of a topic, but not dangerous:
>note >This notice is important.
This snippet renders as:
This notice is important.
callout notice to present information that is relevant to the topic, but not critical to the reader’s comprehension:
>callout >Called out content.
This snippet renders as:
Called out content.
Table of Contents Structure
Dev Center automatically generates an article’s table of contents from its
## in markdown) elements.
The following set of headers results in a TOC that includes
Header 1 and
## Header 1 ### Header 1.1 ## Header 2
Ensure that your article’s top-level headers provide an accurate outline of the article’s content.
Trademarks, Brand Names, and Feature Names
Capitalize “Heroku”. When referring to the URL, use “heroku.com”.
Use “Salesforce org”, not “Salesforce organization”.
Capitalize product brand names to set trademarks apart from other words. Here are some examples:
- Apache Kafka for Heroku
- 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 Shield
- Heroku Redis
- Salesforce Connect
If it’s obvious from context that a product or feature is from Heroku, you can omit “Heroku”.
Capitalize feature names only if they are brand names. If there’s a marketing campaign around it, it’s also appropriate to capitalize a feature name that’s not a brand name.
When referring to trademarks that are owned by other companies, follow their trademark guidelines.
This article contains the style guidelines for the Heroku Dev Center. When writing an article, you must also adhere to the Voice and Tone and Content Guidelines. For more info, see Writing a Dev Center Article.