Writing a Dev Center Article

Last updated 25 May 2016

Dev Center contains a diverse collection of articles from both internal and external contributors across a variety of topics including platform reference material, getting started guides and general web application development tutorials. Having a standardized tone, style and structure ensures cohesion and consistency across this content.

This guide documents the characteristics of a well-written Dev Center article and the shared expectations around its creation.

Style

Factual tone

Stylistically the tone of the Dev Center is both factual and academic. In standard how-to fashion, focus on the steps and rationale necessary to convey the subject matter in a clear, concise and confident manner.

For instance, avoid using language such as “it seems”, “probably” and other non-determinant phrases. 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 narrative uses “you” to address the reader and works well because it allows the use of the imperative voice, is concise and focuses on the reader^[1]. Using “I” or “we” (a first-person narrative) is discouraged in the Dev Center.

Instead of relating the reader to your personal experiences:

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.

Succinctly present the concept based on its own merits:

The foo gem reflects real world experience and gives you the ability to transparently upload static assets at deploy time.

Tense

The present tense should be used when possible to convey temporal relevance. was created, was built and other was ... phrases are an indication of the unnecessary use of the past tense.

The following guide was created to quantify the characteristics of a well-written Dev Center article.

Should be re-stated as:

The following guide quantifies the characteristics of a well-written Dev Center article.

Structure

Introductory statement

Provide a brief overview of the problem or situation the content is intended to address as the article introduction. Compel readers to engage with the content by providing supporting motivation and a clear problem statement. Sell the problem or opportunity at hand.

For reference, here is the introductory statement from this very article.

The Dev Center contains a diverse collection of articles from both internal and external contributors across a variety of topics including platform reference material, getting started guides and general web application development tutorials. Having a standardized tone, style and structure ensures cohesion and consistency across this content.

This guide quantifies the characteristics of a well-written Dev Center article and the shared expectations around its creation.

Title

Dev Center article titles should contain reference to the major language, framework and concepts being presented.

Database-Driven Web Apps with Play!

Doing so clearly defines the purpose and ensures accurate recognition by readers viewing the article title within a list of other search results.

Section titles

All section titles should use sentence-casing. For instance, use:

This is a sentence case title

Instead of:

This is Not a Sentence Case Title

Sequence

Content should be structured in sequential fashion. Keep the work-flow as linear as possible to minimize the cognitive overhead. Provide clear article structure through the use of H2/3/4 section headers (##, ###, etc…)

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.
• 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.
• 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. The Salesforce Style Guide also contains some capitalization guidelines.

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 Connect
• Heroku Dev Center
• Heroku Elements Marketplace
• Heroku Enterprise
• Heroku Kafka
• Heroku Platform
• Heroku Postgres
• Heroku Private Spaces
• Heroku Redis
• Heroku Toolbelt

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.

Conclusion

This guide identifies the patterns present within successful articles and the collaborations that produce them. Following the framework presented here aids in the Dev Center authorship process and ensures a consistent experience for readers.