Writing a Dev Center Article
Last updated September 27, 2021
Table of Contents
Heroku team members and add-on providers write and maintain Dev Center articles. This guide describes the writing process for Heroku Dev Center articles at a high level.
Non-Dev Center contributors can use this article as a reference for establishing conventions for their own documentation projects.
Step 1: Choose the Article’s Goal
Create content for an actual use case. Ensure your article has a clear goal.
Consider who your audience is, their situation and motivation, and the expected outcome. It can be helpful to express this goal in a sentence. For example, the goal of Connecting to a Private or Shield Heroku Postgres Database from an External Resource is:
As a developer, I want to connect to Heroku Postgres externally so that my non-Heroku apps can use the data.
Step 2: Search for Related Articles
Search the Dev Center for articles related to your topic. This search can help narrow down the scope of what to include, as well as indicate content gaps to fill with your article.
Step 3: Create an Outline
Many writers find it helpful to create an outline before writing their drafts. You can structure your article with major headings and bullet point notes to get started.
Step 4: Create a Draft Article
Follow these writing guidelines to ensure a consistent reading experience for users:
Step 5: Check Content for Accuracy
Get subject matter experts to review and approve your content for accuracy.
Verify Instruction Steps and Examples
You’re responsible for performing all steps to ensure accuracy. Whenever possible, use a fresh development environment to do so.
Step 6: Get Your Article Edited and Published
Heroku team members can notify the Dev Center team to review their article. This editorial review is the last step before publishing. Ensure that a subject matter expert approved the article before this final review. Dev Center editors make any necessary edits to conform to writing guidelines before publishing.
Add-on providers can follow the submission process in the Add-on Partner Portal to get their work edited, approved, and published.