Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • ドキュメント
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • ドキュメント
  • 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 のアーキテクチャ
    • Dyno (アプリコンテナ)
    • スタック (オペレーティングシステムイメージ)
    • ネットワーキングと DNS
    • プラットフォームポリシー
    • プラットフォームの原則
  • コマンドライン
  • デプロイ
    • Git を使用したデプロイ
    • Docker によるデプロイ
    • デプロイ統合
  • 継続的デリバリー
    • 継続的統合
  • 言語サポート
    • Node.js
    • Ruby
      • Rails のサポート
      • Bundler の使用
    • Python
      • Python でのバックグランドジョブ
      • Django の使用
    • Java
      • Maven の使用
      • Java でのデータベース操作
      • Java の高度なトピック
      • Spring Boot の使用
    • PHP
    • Go
      • Go の依存関係管理
    • Scala
    • Clojure
  • データベースとデータ管理
    • Heroku Postgres
      • Postgres の基礎
      • Postgres Getting Started
      • Postgres のパフォーマンス
      • Postgres のデータ転送と保持
      • Postgres の可用性
      • Postgres の特別なトピック
    • Heroku Redis
    • Apache Kafka on Heroku
    • その他のデータストア
  • モニタリングとメトリクス
    • ログ記録
  • アプリのパフォーマンス
  • アドオン
    • すべてのアドオン
  • 共同作業
  • セキュリティ
    • アプリのセキュリティ
    • ID と認証
    • コンプライアンス
  • Heroku Enterprise
    • Private Space
      • インフラストラクチャネットワーキング
    • Enterprise Accounts
    • Enterprise Team
    • Heroku Connect (Salesforce 同期)
      • Heroku Connect の管理
      • Heroku Connect のリファレンス
      • Heroku Connect のトラブルシューティング
    • シングルサインオン (SSO)
  • パターンとベストプラクティス
  • Heroku の拡張
    • Platform API
    • アプリの Webhook
    • Heroku Labs
    • アドオンのビルド
      • アドオン開発のタスク
      • アドオン API
      • アドオンのガイドラインと要件
    • CLI プラグインのビルド
    • 開発ビルドパック
    • Dev Center
  • アカウントと請求
  • トラブルシューティングとサポート
  • Integrating with Salesforce
  • Heroku の拡張
  • アドオンのビルド
  • アドオンのガイドラインと要件
  • アドオンドキュメントのガイドライン

アドオンドキュメントのガイドライン

日本語 — Switch to English

最終更新日 2020年07月13日(月)

Table of Contents

  • 重複したドキュメント
  • スターターテンプレート
  • 内容
  • 例
  • 提出
  • 保守

Heroku アドオンカタログは、大規模で多様な技術者のグループに向けてアドオンを紹介し、アドオンの導入を加速させたり知名度を高めたりできる独特のマーケティングチャネルです。Dev Center のドキュメントを適切に記述し、保守することは、さまざまな言語コミュニティに向けてサービスの長所を明確に示すために重要であり、アドオンをアプリケーションに統合することを検討している開発者に安心を与えます。

重複したドキュメント

多くのアドオンパートナーは、自社のサイトで製品ドキュメントを保守します。また、記事全体に自社サイトのドキュメントへのリンクを散りばめたり、最低限のドキュメントだけを提供してパートナーのサイトに役割を委ねることによって、重複する領域をなくそうとします。このような文書化アプローチは Dev Center には適切ではありません。

開発者は、プラットフォームとアドオンに関連したすべてのトピックの最初のリソースとして Dev Center に注目しており、この最初のアクセスで開発者の疑問点をできるだけ解消できるようにする必要があります。先述したようなアプローチでは、読者は Dev Center の外部にアクセスする必要があり、一貫性がなく不便なエクスペリエンスを強いられます。Heroku ではユーザーエクスペリエンスを最も重視しています。

さらに、Dev Center そのものがマーケティングチャネルであると考える必要があります。チャネルごとに異なるターゲットに情報を直接伝えるために、ある程度のコンテンツを複製することが必要になります。管理のオーバーヘッドはやや増えますが、ビジネス面のメリットはそれを補って余りあります。

スターターテンプレート

アドオンにあまり詳しくない開発者は、アドオンが提供する機能や、特定の言語とアドオンを統合する方法はおろか、開発およびテスト中にアドオンを使用する方法についてさえ、ほとんど知識がない場合があります。あらゆるニーズに応えるために、幅広いコンテキストと具体的な例の両方を提供することが重要です。

テンプレートのダウンロード

このタスクを支援するために、Heroku では、アドオンドキュメントの雛形として使用できるスターターテンプレートを提供しています。このテンプレートは、わかりやすさを高め、開発者の混乱を減らすことが実証されたトピックで構成されています。

編集のためにテンプレート​をローカル環境にコピーします。

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

Dev Center のドキュメントの記述には、テキストベースの GitHub Flavored Markdown 形式を少し拡張したものを使用します。任意のテキストエディタを使用して記事を編集できます。

スタブの置き換え

記事を開き、以下のキーワードを、アドオンの記事にふさわしい値に置き換えます。

​置換前 ​置換後
​ADDON-NAME ​アドオンの名前。例: ​​New Relic
​ADDON-SLUG ​CLI やアドオンサイトの URL で使用される短縮名。例: ​​newrelic
​ADDON-CONFIG-NAME ​統合後のアプリに公開するアドオン設定の名前。例: ​​CLOUDANT_URL

[[​ ]]​ のかっこで囲まれたセクションは作成者向けのメモであり、公開前に削除する必要があります。

内容

スターターテンプレートのセクションの多くは、文書化しているアドオンに適さない場合があります。そのような場合、該当するセクションを削除することができます。ただし、これは例外であってルールではありません。これらのセクションは、アドオンの潜在的なユーザーに最高のエクスペリエンスを提供することが実証されているからです。

執筆ガイド

Dev Center 全体でエクスペリエンスに一貫性を持たせるために、Heroku では、スタイル、構造、フォーマットの明確なガイダンスを含む執筆ガイド​を作成しました。執筆ガイドの内容を理解して、アドオンのドキュメントと Dev Center の他のコンテンツの間で一貫性を保つようにしてください。

アドオンについて

最初のセクションでは、提供しようとしているサービスの詳細を説明してください。特に含めるべき情報は、サービスの機能、サービスの利点、マーケットプレースにある他のサービスとの差別化ポイントの 3 点です。開発者には、さまざまなアプリケーションサービスの選択肢があります。この説明は、提供するサービスの価値を開発者に納得させるチャンスと考えてください。

コードサンプル/多言語

Heroku は多言語プラットフォームです。アドオンでは、サポートしている言語でコードサンプルを提供することによって、多言語アプリケーション開発のニーズにも応える必要があります。スターターテンプレートのいくつかの領域では、コードと統合のサンプルが Ruby で提供され、他の言語用のプレースホルダーがそれに続く形になっています。他の言語のセクションも、Ruby セクションに劣らないよう、できるだけ詳しい内容にしてください。

Heroku の開発者ベースは多言語化が進んでいるため、1 つの言語のサポートしか文書化していないと、アドオンの潜在的な市場を大きく狭めることになります。

レンダリングツール

多くのサービスでは、Markdown から HTML へのレンダリングをサポートしています。広く使用されているツールの 1 つが GitHub Gists​ です。執筆中、プライベートな gist に記事を保存し、これを使って他の開発者と共同作業するのは一般的で便利なやり方です。

執筆サポート

レビューやフィードバックを希望する場合は、Heroku アドオンチーム (addons@heroku.com​) までご連絡ください。

例

CloudAMQP アドオンのドキュメント は、執筆の質が高く、一貫性があり、多言語に対応したドキュメントの良い例です。

提出

アドオン記事の執筆を終了したら、アドオンパートナーポータル​の提出プロセスに従って ドキュメントを提出してください。

保守

ドキュメントの内容は、アドオンとの関連性がなければ意味がありません。Dev Center のドキュメントを、新しいバージョンおよび言語リリースと整合性のある最新の状態に維持するのはアドオンパートナーの責任です。

関連カテゴリー

  • アドオンのガイドラインと要件
顧客の利用プラン管理ガイドライン (アドオンパートナー向け) アドオンパートナーのためのアドオン所有権モデルとユーザー認証のガイドライン

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