このガイドでは、Discourse 向けの効果的なハウツードキュメントの作成方法について説明します。構造やスタイル、対象読者の考慮、メンテナンスなど、重要な要素を網羅しています。
必要なユーザーレベル：誰でも新しいハウツーガイドを作成できます
Discourse 内でユーザー、モデレーター、管理者、システム管理者がさまざまなタスクを実行する際に役立つよう、効果的なハウツードキュメントを作成することは極めて重要です。このガイドでは、コミュニティ向けに明確で価値のあるハウツーガイドを執筆する方法をご紹介します。
まとめ
このドキュメントでは、以下について学びます：
- なぜハウツー記事を書くことが重要なのか
- どのような情報を含めるべきか
- 構造とスタイルに関するガイドライン
- 投稿先の場所
- 投稿後のメンテナンス方法
なぜハウツー記事を書くのか？
何かタスクを実行する必要があり、その方法を思い出せない経験はありませんか？Discourse におけるプロセスを文書化する優れた方法は、ハウツー記事を作成することです。もしあなたが特定のプロセスでつまずいているなら、他の人も同様である可能性が高いです。それを文書化することは、全員にとって役立ちます。
ハウツー記事がチュートリアルやリファレンスガイドなどの他のドキュメントタイプとどう異なるかについては、Divio のこのガイドをご覧ください。
ハウツー記事の作成やレビューは、Discourse の知識をコミュニティに貢献する素晴らしい方法です。 他の貢献方法については、Discourse への貢献方法のガイドをご覧ください。
どのような情報を含めるべきか？
ハウツー記事は、ユーザーを特定の最終結果へと導くステップバイステップのガイドであるべきです。例えば、「Discourse への HTTPS 設定」と題されたハウツー記事は、HTTPS の設定手順を提供する内容である必要があります。
ハウツーガイドを作成する際に覚えておくべき重要なポイント：
- トピックに絞り、明確に記述する
- 不要な情報は避ける
- 簡潔でありながら情報豊かにする
- 最終結果を達成することがなぜ有益なのかを説明する
対象読者を考慮する
Discourse のハウツー記事には、説明の深さが異なるさまざまな対象読者がいます。ガイドの対象読者を決める際には、ドキュメントのカテゴリーを参考にしてください：
- Documentation > Using Discourse
- Documentation > Site Management
- Documentation > Integrations
- Documentation > Hosted Customers
- Documentation > Self-Hosting
- Documentation > Migrating to Discourse
- Documentation > Developer Guides
- Documentation > Contributing
対象読者の技術スキルレベルを理解し、それに応じてガイドを調整してください。いくつかのヒント：
- 対象読者が実行できないステップを避ける（例：ホスト型顧客は一般的にコンソールコマンドへのアクセス権を持っていません）
- 指示を明確にし、非技術的なユーザーに対して高度な技術用語を避ける
- 対象読者がすでに知っているはずの背景情報を追加しない
構造とスタイル
ドキュメントスタイルガイドでは、ハウツーガイド（および他のすべての Discourse ドキュメント）の構造とスタイルについて必要な情報をすべて網羅しています：
ガイドを投稿する
ガイドは、親カテゴリーである Documentation のサブカテゴリーに投稿し、how-to タグを付けます。すべてのガイドは Discourse チームによる承認が必要ですが、これはモデレーションプロセスを通じて自動的に処理されます。スタイルガイドでは、各カテゴリーについて詳しく説明しており、ガイドを投稿する場所を決める際の参考になります。
ガイドのメンテナンス
ハウツー記事を投稿したら、常に最新の状態に保ちましょう。メンテナンスに役立つ方法は以下の通りです：
- 返信に注意する — コミュニティからのフィードバックをガイドに反映させる。
- 自分でガイドを試す — 定期的にガイドを確認し、正確性を保つ。
- 不足または誤った情報を修正する — 信頼レベル 2 以上であれば、ハウツー記事の最初の投稿を編集する。
- サポートのためにトピックをフラグ付けする — 編集ができない場合は、「その他」でフラグを付け、必要な対応を説明する。
ほとんどの場合、公式のハウツーガイドでは、ガイド自体への注目を維持するため、1 ヶ月後にコメントが削除されます。
Discourse コミュニティのドキュメント向上にご協力いただきありがとうございます！もし行き詰まったら、遠慮なく助けを求めてください。最も良い始め方は、貢献しながら学び続けることです。