Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Building Add-ons
  • Add-on Guidelines & Requirements
  • Add-on Documentation Guidelines

Add-on Documentation Guidelines

English — 日本語に切り替える

Last updated July 13, 2020

Table of Contents

  • Duplicate documentation
  • Starter template
  • Content
  • Examples
  • Submission
  • Maintenance

The Heroku Add-on catalog is a unique marketing channel that places the add-on in front of a large and diverse group of technologists and is capable of accelerating its adoption and awareness. Well-written and maintained Dev Center documentation is central to clearly identifying the service benefits to the various language communities and provides confidence to developers considering integrating the add-on into their application.

Duplicate documentation

Many add-on partners maintain product documentation on their own site and attempt to remove all areas of duplication by linking to their site documentation throughout the article or by providing a very thin document that delegates back to the partner’s site. This documentation approach is not appropriate for the Dev Center.

Developers look to the Dev Center as their first resource for all topics surrounding the platform and add-ons and as many of their questions as possible should be answered on this initial visit. It creates a very inconsistent and poor experience for the reader to have to navigate outside the Dev Center. The user experience is paramount at Heroku.

Additionally, the Dev Center should be thought of as its own marketing channel. Different channels necessarily duplicate some content to speak more directly to that particular audience. The business benefits far outweigh any minor administrative overhead incurred.

Starter template

Developers unfamiliar with an add-on may have very little knowledge about the functionality it provides, how to integrate it with their preferred language or even how to use it during development and testing. It is important to provide both broad context and specific examples to ensure complete coverage.

Download template

To aid in this task, Heroku provides a starter-template that can be used as a starting point for add-on documentation. It includes topics that have been found to increase clarity and reduce developer confusion.

Copy the template to your local environment for editing.

$ curl https://devcenter.heroku.com/articles/add-on-template.md > addon-doc.md

Dev Center documentation is written using a slight extension to the text-based GitHub Flavored Markdown format. Any text editor can be used to edit the article.

Replace stubs

Open the article and replace the following keywords with the appropriate values for the article’s add-on.

Replace… with
ADDON-NAME The name of the add-on. E.g. New Relic.
ADDON-SLUG The shorthand name used by the CLI and Add-on site URL. E.g. newrelic.
ADDON-CONFIG-NAME The name of the add-on config expose to integrated apps. E.g. CLOUDANT_URL.

Sections wrapped in [[ ]] brackets are notes to the author and should be removed before publishing.

Content

Many of the sections in the starter template may not be appropriate for the add-on being documented. In such cases the sections can be removed. However, this should be the exception and not the rule as these sections have been found create the best experience for potential users of the add-on.

Writing guide

In order to provide a consistent experience across the Dev Center, Heroku has created a writing guide with clear style, structure and formatting guidance. Please read the writing guide to ensure the add-on documentation maintains consistency with the rest of the Dev Center content.

About the add-on

Please describe the details of the service you are providing in the opening section. Information you may want to include are: 1) how the service works 2) the benefits of your service. 3) how your service differs from other options in the market place. Developers have many choices in application services, use this as an opportunity to convince them of the value of your offering.

Code samples/polyglot

Heroku is a polyglot platform. Add-ons should also support the tenet of polyglot application development by providing code samples in languages supported by the add-on. The starter template has several areas where code and integration samples are given in Ruby followed by a placeholder for other languages. Please complete the other language sections with as much detail as the Ruby section as possible.

Documenting support for only a single language severely limits the potential market for the add-on amongst Heroku’s increasingly polyglot developer-base.

Rendering tools

Many services support the rendering of Markdown into HTML. One commonly used tool is GitHub Gists. Storing the article in a private gist and using it to collaborate with others during the writing process is a common and convenient practice.

Writing support

If review and feedback is desired, please contact the Heroku Add-ons team at addons@heroku.com.

Examples

The CloudAMQP add-on documentation is a great example of a well-written, consistent and polyglot document.

Submission

Once the add-on article has been created, please follow the submission process in the Add-on Partner Portal to submit the documentation.

Maintenance

Content is only as compelling as it is relevant. Add-on partners should ensure their Dev Center documentation stays up-to-date with new versions and language releases.

Keep reading

  • Add-on Guidelines & Requirements

Feedback

Log in to submit feedback.

The Add-on Ownership Model and User Authentication Guidelines for Add-on Partners Add-on Partner Technical Best Practices

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences