アドオンドキュメントのガイドライン
最終更新日 2024年04月24日(水)
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 のドキュメントを、新しいバージョンおよび言語リリースと整合性のある最新の状態に維持するのはアドオンパートナーの責任です。