前のチュートリアル: Developing Discourse Plugins - Part 6 - Add acceptance tests
あなたはプラグインを作成し、GitHubにアップロードし、テストを追加しました。素晴らしいですね！問題は、他の誰もそれについて知らないということです。
プラグインのドキュメント化
すべてのプラグインには良いドキュメントが必要です。ユーザーは、プラグインが何をするのか、どのようにインストールするのか、必要な重要な設定/構成の変更、および使用方法を知る必要があります。プラグインは2つの異なる場所でドキュメント化されるべきです：gitリポジトリ内のREADME.mdファイルと、#customization:pluginカテゴリの専用トピックです。
GitHubドキュメント
GitHub上のREADME.mdファイルは、ユーザーがあなたのリポジトリを訪れたときにデフォルトで表示されるため重要です。最低限、あなたのREADMEにはプラグインのタイトルと短い説明を含めるべきです。より完全なREADMEには、インストール手順、より詳細な説明、基本的な使用方法、ライセンス、および（該当する場合）スクリーンショットも含まれます。追加の手順があなたのプラグインのMetaトピックに含まれている場合は、トピックへのリンクを必ず含めてください。
最小限のドキュメント化されたプラグインの例: Discourse Data Explorer
より完全なドキュメントを持つプラグインの例: Discourse Solved, Discourse OAuth2 Basic, および Discourse Ads.
サンプルプラグインREADMEテンプレート
<>で囲まれたテキストをあなたのプラグインの具体的な情報で更新してください。
## <プラグインタイトル>
<プラグインの説明>
## インストール
[プラグインインストールガイド](https://meta.discourse.org/t/install-a-plugin/19157)に従ってください。
## 使用方法
<プラグインの有効化方法、必要な設定手順、および使用方法を説明>
## スクリーンショット
<プラグインの使用を説明するために必要な場合はスクリーンショットを含める>
## さらに読む
<Metaトピックに詳細な情報がある場合はリンクを含める>
## ライセンス
<コードライセンスを記載、ほとんどのDiscourseプラグインはMITを使用>
Metaドキュメント
GitHubドキュメントが短く「要点を絞った」ものであるのに対し、Metaドキュメントではプラグインの全詳細を共有し、ユーザーに使用すべき理由を説得する場所です。最低限、あなたのMetaトピックにはプラグインの短い説明と、GitHub上のプラグインリポジトリへのリンク（ユーザーがインストールできるように）を含めるべきです。より完全なドキュメントには、例示的なユースケース、詳細な使用手順、すべての設定と構成オプションのドキュメント、およびスクリーンショットも含まれます。スクリーンショットは重要で、ユーザーはプラグインが何をするのか見たいと考えています。認証プロバイダーを追加するプラグインは1枚のスクリーンショットで十分かもしれませんが、新しいインターフェースを追加したり、大きな変更を行うプラグインはそれなりに多くのスクリーンショットが必要です。
MetaドキュメントはGitHubよりも個人的な傾向があり、各プラグイン作者は独自のドキュメントスタイルを持っています。どのようなスタイルを選んでも、明確で読みやすく、整理されていることを確認してください。適切にヘッダーを使用し、複雑な相互作用を説明するためにスクリーンショットに注釈を付け、フォーマットの一貫性を保ってください。巨大な段落を書く誘惑に陥らないようにしてください。
ドキュメントの更新
初期ドキュメントを作成した後、それを最新に保つことが重要です。
プラグインに新しい機能を追加しましたか？それをドキュメント化する時間を必ず確保してください。
同じ質問に何度も答えましたか？MetaトピックにFAQセクションを追加することを検討してください。
修正が複雑な既知の問題がありますか？ユーザーが期待できることを知らせるためにトピックに詳細を記載してください。
プラグインのサポート
プラグインとそのドキュメントを公開した後、それを有用だと判断したサイト管理者が自分のサイトにインストールし、使い始める可能性があります。この使用にはプラグイン開発者による継続的なサポートが必要です。サイト管理者の質問に答え、プラグインの使用を助ける必要があります。あなたには完璧に理解できたことが、他の人にとっては不明確かもしれませんので、コードと/またはドキュメントを更新してそれを明確にする必要があります。機能リクエストを受け取る可能性があり、それらを追加するかどうかを決定する必要があります。
最後に、Discourse自体は絶えず開発されています。あなたのプラグインが今日完璧に動作していても、明日に変更が加えられて壊れる可能性があります。Discourseの開発状況を常に把握し、変更があなたのプラグインに影響を与える場合に最新のDiscourseバージョンをサポートするようにプラグインを更新できるようにしてください。
シリーズの続き
パート1: プラグインの基本
パート2: プラグインアウトレット
パート3: サイト設定
パート4: gitセットアップ
パート5: 管理者インターフェース
パート6: 受け入れテスト
パート7: このトピック
このドキュメントはバージョン管理されています - 変更提案はgithubで行ってください。
