Last updated May 04, 2023

This article contains the content 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.

Article Length

The max limit for an article is 1500 words. Exceptions to this are pure reference articles, such as the Platform API Reference.

Review your article for wordiness. Apps like Hemingway help point out sentences that are overly complex.

If your article is more than 1500 words, it likely serves more than one purpose. Carefully define what your article solves and split it up into smaller articles for each purpose.

Article Title and Introduction

Optimize the title for search. Include the keywords that are most relevant to your topic. Remember to use title capitalization.

For conceptual or reference topics, the title can be just the name of the product or feature. For articles with topics that are task-oriented, start the title with a gerund. For example,

Connecting to Relational Databases on Heroku with Java

Begin the article with a short overview of its contents. Say specifically what use case or problem the article solves.

Complexity

For conceptual articles on a particular technology, introduce it with a use case. Describe the technology’s most universally applicable concepts before introducing advanced or obscure use cases.

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

Dates

Only use dates when necessary. Beware of “currently”, “last week” or “last year” or “the new”. These statements assume that the user is reading your doc at a particular point in time.

In most cases, you can avoid using dates. If you must use dates, such as for upcoming deprecations, use the following guidelines:

1. Reference a specific Heroku changelog item.
2. Set a reminder to remove the date from the article in the future, either on your end or with the Heroku Dev Center team.

Example Code Repositories

Include deployable example applications when possible. A deployable reference application is a great way to convey the totality of a particular approach. This reference 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
>The source for this article's [reference application](https://github.com/xyz) is available on
>GitHub.

Include README instructions for running the application both locally and on Heroku using standard CLI commands in the GitHub project.

Inclusion

Avoid gender-specific pronouns and possessives. Try using the second-person singular (you), omitting the pronoun, or making the noun plural. If using a third-person pronoun is unavoidable, use “they”. Avoid “he” or “she” and “his” or “her”.

If using “they” as a third-person singular, be careful to avoid ambiguous pronoun references. For example, if a singular and a plural noun are in one sentence, don’t use “they” to refer to the singular one.

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

To support a global audience, think carefully before you use colloquialisms and cultural references in your content.

Use inclusive language in your articles.

If you must use noninclusive terms because it’s used in third-party systems, include this callout at the top of your article:

Section Headings

Use title capitalization. For task-based sections, start the heading with a verb using the imperative. For example:

Create a Mapping

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.

Trademarks, Brand Names, and Feature Names

See the Heroku Dev Center Style Guidelines for more info.

Word List

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

• add-ons: Not addons. When referring to an instance or a service, use lowercase (for example, installing an add-on). When referring to our product, capitalize it (for example, 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’s 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.”
• hard code, hard-coded: Two words as a verb or noun; hyphenated as an adjective.
• 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’s 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: Don’t 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).

Third-Party Links

While third-party linking isn’t prohibited, there are some considerations.

In general, try to avoid linking to external sites. Evaluate the safety, accuracy, and endurance of the content to which you’re linking:

• Is it a trusted site with little risk of getting hacked or overrun by malware?
• Is the content likely to be updated or changed soon?
• Don’t link directly to downloads. Link to the landing page for the download instead.
• Avoid linking to personal blogs, non-Salesforce community sites, and frequently updated sites.

Third-Party Tools

A Dev Center article introduces or recommends a third-party tool, library, or framework only if the supported default technologies are meaningfully less effective.

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

Additional Guidelines

This article contains the content guidelines for the Heroku Dev Center. When writing an article, you must also adhere to the Voice and Tone and Style Guidelines. For more info, see Writing a Dev Center Article.