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