Discourse向け効果的なドキュメンテーションの書き方

ドキュメント 貢献
1

:information_source: Discourse ドキュメントは現在、このスタイルガイドに合わせるためにレビューおよび編集されています。すべてのドキュメントトピックが現時点でこのガイドと一致しているわけではありませんが、可能な限り迅速に一致させるよう努めています。

これは、Discourse ドキュメントの書き方と書式設定を導く「生きているドキュメント」と見なされます。このトピックは必要に応じて最新の状態に保たれます。ここに記載されている原則について不明な点がある場合は、そのトピックに投稿して具体的な事項について議論してください。

このドキュメントスタイルガイドの基本的な原則は、ドキュメントを書く際に読者とそのニーズを考慮することです。彼らは何を達成したいのでしょうか？コンテンツを提供するあなたの目的は何でしょうか？

:eyes: スタイルガイドを実装する際の簡単なチェックリスト：

  1. メタブロックが存在し、正しいこと
  2. タイトルが行動指向であること
  3. すべてのタイトルが文頭大文字（Sentence case）であること
  4. 正しいタグとカテゴリが使用されていること
  5. ドキュメントが論理的に構造化されていること

ドキュメントを完成させたら、すべての基準が満たされているか確認してください。

以下のテキスト書式設定ガイドラインに注意してください。

メタ情報

  • ドキュメントは、以下のカテゴリの「1 つかつ唯一 1 つ」に属している必要があります：
    • Discourse の利用
      • 管理者以外のタスクに関する一般ユーザー向けガイド
    • サイト管理
      • 設定、プラグイン、コンテンツ、および一般的なサイト管理
    • 統合
      • 他のプラットフォームを Discourse と統合するためのガイド
    • ホスト型顧客向け
      • ホスト型顧客にのみ関連するガイド
    • 自己ホスティング
      • 自己ホスティングサイトにのみ関連するガイド
    • 開発者向けガイド
      • テーマ、テーマコンポーネント、プラグインの作成を含む、Discourse 上での開発に関する技術的ガイド
    • 貢献
      • Discourse オープンソースプロジェクトへの貢献に関するガイド
  • ドキュメントは、以下のタグ/ドキュメントタイプの「1 つかつ唯一 1 つ」に属している必要があります：
    • #how-to
    • #explanation
    • #reference
    • #tutorial
  • ドキュメントには他の適用可能なタグを付与できますが、1 つのドキュメントに付与できるタグの最大数は 5 つです

メタブロック

すべてのドキュメントには、ドキュメントの内容についての短い説明と、必要なユーザーレベル要件、コンソールアクセスの要否など、関連する追加メタ情報を含むブロックを冒頭に配置する必要があります。これは見出しなしの引用ブロックとしてフォーマットされます。以下はその例です：

:bookmark: これは、利用可能なすべての隠しサイト設定の説明、有効化方法、および調整する理由について記述したガイドです。

:person_raising_hand: 必要なユーザーレベル：管理者

:computer: コンソールアクセスが必要

タイトルと見出し

  • ドキュメントタイトルは行動指向にしてください
    • 不適切：「チャットスレッドの自動タイトルの有効化方法」
    • 適切：「チャットスレッドの自動タイトルの有効化」
  • ドキュメントタイトルは長すぎないこと
  • 「how-to」トピックの場合は、タイトルを目標指向にしてください
  • すべてのタイトルは具体的かつ一意である必要があります
  • ドキュメントタイトルには、カンマ以外の句読点や特殊文字を使用しないでください
  • ドキュメントタイトルに絵文字を含めないでください
  • タイトルと見出しには文頭大文字（Sentence case）を使用してください。つまり、最初の単語と固有名詞、通常大文字になる単語以外は小文字で開始します
  • 見出しではアンパサンド（&）を使用せず、代わりに完全な単語（“and”）を使用してください

一般的な執筆ガイドライン、トーン、および文法

  • ドキュメントを読む人を指す場合は、二人称 を使用してください。つまり、「私達」ではなく「あなた」を使用します
  • 可能な限り能動態を使用してください
    • 不適切：「ボタンをクリックする必要があります」
    • 適切：「ボタンをクリックしてください」
  • 略語や頭字語は初回使用時に定義し、必要に応じて詳細情報を提供する外部リンクを提供してください
  • 文は短くし、短い段落、見出し、リストを使ってテキストを分割してください
  • 重要なフレーズや単語を強調するために **太字** や *イタリック* を使用できますが、使いすぎないでください
  • 説明なしで専門用語や技術用語を使用するのは避けてください。不明な場合は、説明を優先してください
  • UI 要素などの視覚的インターフェースを説明する際は、スクリーンショットを使用してください
  • 明示的に許可されていない限り、将来の Discourse の機能、製品、またはサービスについて記述したり開示したりしないでください
  • したがって、しかしながら、さらに などの接続詞を使用してください
  • 一般的な縮約形を使用してください：it’s, you’ll, you’re, we’re, let’s
  • ドキュメントでは「永遠性」を推測してください。soon、new、now、latest など、すぐに無効になるような言葉は避けてください
  • ソフトウェアやハードウェアに人間の性質を帰属させないでください
    • 例：「この API に整数を渡すと、怒ってエラーを発生させます」
    • 例：「私たちの親しみやすく野心的な AI ボットがすべての問題を解決します」
  • テキスト（Discourse UI からのものを含む）を引用する場合は、"引用符" を使用してください
  • URL を引用する場合は、バッククォート を使用してください
  • 例示用のドメインを使用する場合は discourse.example.com を使用してください
  • 有益であれば、段落の冒頭に絵文字を使用して強調できます。1 つのトピックで使用する絵文字は 2〜3 個を超えないでください。使用できる絵文字の例：
    • :information_source: - 情報的な注記
    • :mega: - 発表またはお知らせ
    • :warning: - 警告メッセージ
    • :exclamation: - 非常に重要な情報
  • 避けるべきこと：
    • 不要な比喩やユーモア
    • 文化的・地域的な参照
    • 上から目線の命令調の手順 - 例：「必ず公開をクリックしてください」 または 「公開をクリックする必要があります」
    • 過度に丁寧であること。例：「公開をクリックしてください」
    • 絶対的に必要な場合を除き、感嘆符を使用しないこと
    • 不必要な箇所で単語を大文字にすること
    • 同じフレーズや代名詞の過剰な使用

エンドユーザー向けドキュメントの場合：
親しみやすくカジュアルなトーンを維持し、知識に基づいた明確さと簡潔さに焦点を当ててください。すぐに本題に入ってください。技術用語は説明してくださいが、上から目線にならないように注意してください。明確さを確保するために、まず現在のトピックの文脈を簡単に指定することから始めます。

開発者および技術ドキュメントの場合：
直接的で正確なトーンを維持してください。ユーザー向けドキュメントと同じトーンを使用しますが、読者がより高度な技術的知識を持っていると想定しても構いません。

構造

  • すぐに本題に入ってください - 最も重要なことから始めましょう
  • 重要なキーワードをドキュメントの早い段階で含めてください
  • 読者の選択肢と次のステップを明確にしてください
  • ドキュメントの作成には常に軽量マークアップを使用してください（これは Markdown-it を使用して Discourse に既に組み込まれています）。
  • ドキュメントを論理的な流れで整理してください - 概要から始め、詳細なセクション、そして該当する場合は要約または結論で終わります
  • 見出しとサブ見出しを使用してコンテンツを構造化し、読者が特定の情報を読みやすく検索しやすくしてください - 見出しでは h2 から始めて階層を降順に配置し、レベルを飛ばさないでください
  • ドキュメント内の関連トピックやセクションへのリンクを提供してください - これにより、ユーザーは不要な検索なしで追加情報を見つけることができます

リンク

  • リンクには意味のあるテキストを使用してください
    • 不適切：「ガイドを読むにはこちらをクリックしてください」
    • 適切：「ガイド を読む」
  • URL の形式が重要または教育的でない限り、リンクテキストとして URL を使用しないでください。代わりに、ページタイトルまたはページの説明を使用してください
  • 既存のドキュメントを引用または書き換える代わりに、外部サイトやソースにリンクしてください
  • リンク先のサイトが高品質であることを確認してください
  • リンクがファイルをダウンロードする場合は、明示的に記載してください。また、ダウンロードされるファイルの種類と概算ファイルサイズも示してください

ドキュメント内のコード

  • 大規模なコード例では、可能な限り言語固有の構文ハイライト付きのブロックコードを使用してください
  • 自明でない場合は、続くコード例を導入する導入文でコード例を紹介してください。不明な場合は、説明を優先してください
  • コード例は、関連するプログラミング言語のベストプラクティスに従う必要があります
  • 基本的なコード属性を表す場合や、完全なコードブロックが不要な場合は、インラインコードを使用してください。例：
    • 属性名と値
    • クラス名
    • コマンドラインユーティリティ名
    • データ型
    • 環境変数名
    • ファイル名、ファイル拡張子、パス
    • フォルダとディレクトリ
    • HTTP 動詞、ステータスコード、コンテンツタイプ値
    • クエリパラメータ名と値
    • テキスト入力
  • コード例、コマンド、またはその他のテキストで プレースホルダー を使用する場合は、そのプレースホルダーが何を表すかの説明を含めてください
    • プレースホルダーを初めて使用する際に説明を書きます。最初の使用後に複数のプレースホルダーや手順がある場合は、プレースホルダーの説明を再度行っても構いません
  • ユーザーや開発者がコードをコピーして実行しやすい方法を提供してください
    • 期待される出力を、コード例の後の別セクションに表示するか、コード例内のコードコメントを使用して示してください
  • 安全なコードを書いてください。パスワード、API キー、または機密情報をコードにハードコードしないでください

手順とステップバイステップガイド

  • 手順を一貫してフォーマットし、読者がスキャンして容易に見つけられるようにしてください
  • 各ステップには番号付きの個別のエントリを使用してください
  • OK や Apply ボタンなど、ステップを完了するアクションを含めてください
  • 指示がアクションが発生するのと同じ UI に表示される場合は、通常、場所の詳細を提供する必要はありません
  • 読者が正しい場所から開始することを確認する必要がある場合は、ステップの冒頭に短いフレーズを提供してください

アクセシビリティと包括性

  • 複雑な手順の説明やインターフェースの一部の表示など、価値を高める場合は、スクリーンショット、図、または動画を使用してください
  • 画像はテキスト情報を補完するために使用し、置き換えるものではないことに注意してください
  • 画像には常に alt 属性を使用してください
  • 動画には常にキャプションまたは文字起こしを提供してください
  • GIF を使用する場合は、内容をテキストで完全に説明できる場合に限ります
  • シンプルな画像を選択し、余計な詳細をトリミングしてください
  • 平易な言語を使用し、普遍的に理解されない可能性のある慣用句や比喩を避けてください
  • ドキュメントが多数のデバイスで使用されることを考慮してください
  • 性別に中立的な言語を使用してください。人を指す際に he, him, his, she, her, or hers を使用しないでください。代名詞を避けるためには、以下の方法があります：
    • 二人称（you）を使用して書き直す
    • 文を複数形の名詞と代名詞になるように書き直す
    • person や individual という言葉を使用する
    • 代名詞の代わりに the, an, または a などの冠詞を使用する
    • 単一の個人を参照する場合でも、they, their, または them などの複数形代名詞を使用する
  • 実在する人物について書く場合は、その人が好む代名詞を使用してください
  • 性自認、人種、文化、宗教、能力、年齢、性的指向、社会経済的階級に対して包括的でありましょう。例には多様な職業、文化、教育環境、地域、経済環境を含めてください
  • 政治的なコンテンツは避けてください。政治的なコンテンツを含める必要がある場合は、中立的に留めてください
  • 人、国、文化について一般化しないでください。肯定的または中立的な一般化であっても同様です
  • いかなるコミュニティ、特に少数民族に対する偏見や差別を含むコンテンツは書かないでください
  • 歴史的出来事に関連する定性的な用語を避けてください
  • 暴力や軍事行動に関連する用語や比喩を使用しないでください
「いいね！」 8
Discourse documentation policy
Documentation contribution opportunities
Writing effective how-to documentation
Experiment: Collaborative content gardening hub for meta
Better documentation navigation with a new sidebar
Understanding and managing post notices
2

@hugh / @SaraDev
タイトルについて、若干の一貫性のなさに気づきました。

以下のような例があります。

しかし、その後、以下のように述べています。

「正解」の例をコンバーターに通すと、以下のようになります。

Enable Automatic Titles for Chat Threads

例をそれに合わせて更新すべきでしょうか？

補足

私個人としては、文の先頭のみを大文字にする（sentence case）方が良いと考えており、現在のトピックタイトルで「Chat Threads」が大文字になっている理由もよくわかりません。そのため、個人的には以下のようにしたいと考えています。

Enable automatic titles for chat threads

しかし、最終的には一貫性が最も重要であり、現在の推奨事項を選択されたのには良い理由があると仮定します。

「いいね！」 1
3

それは良い指摘ですね。私はその関連性に気づいていませんでしたが、簡単に更新できます。しかし：

タイトルケースの指定は私が行ったものです。なぜなら、一般的にタイトルケースの方がすっきりとしていてプロフェッショナルに見えるからです。これは私の主観的な意見だと思います。なぜなら、Google も Microsoft も、ドキュメンテーションのタイトルにはセンテンスケースを使用するように言っています。私が調べた他のサイトでもセンテンスケースを使用するように言われているため、これを元に戻し、そこのケース要件を更新します。

「いいね！」 3
4

また、タイトルと見出しの両方にセンテンスケースを使用するように指示していることにも気づきました。（私も同じチームです。）

見出しに関する私たちの好みは現在指定されていないようです。この機会にそれも追加しましょう。

「いいね！」 1
5

同意します。明示的に指定するためにここに追加します。

「いいね！」 1
6

OK、調子に乗ってきたので…\n\nこれは良いと思います:\n\n[quote="Discourse, post:1, topic:309628"]\n不必要に単語を大文字にする\n[/quote]\n\n\nしかし、ガイドには現在、この例があります。\n\n[quote="Discourse, post:1, topic:309628"]\n:bookmark: これは、利用可能なすべての非表示サイト設定、それらを有効にする方法、および調整する理由を説明するためのガイドです。\n[/quote]\n\n私の意見では、ここで「非表示サイト設定」を大文字にする必要はないと思います。（権威への訴え)

「いいね！」 2
7

お気遣いありがとうございます :smile:

はい、これは良い点です。この例は、既存のドキュメントのタイトルを使用して説明した実際のドキュメントから抜粋したもので、そのドキュメントではタイトルケースが使用されていたため、参照も同様でした。タイトルケースからセンテンスケースに変更されたため、その参照も更新する必要があります。

「いいね！」 1
8

上記の会話に基づいて、このスタイルガイドにいくつか編集を加えました。

  • トピックタイトルを文頭大文字に変更しました
  • 見出しを文頭大文字に変更しました
  • 不要な大文字（Syntax）を削除しました
  • 見出しのアンパサンド（&）を「and」に置き換えました
  • 見出しのスラッシュ（/）をコンマまたは接続詞に置き換えました

最後の2つの変更については議論されていません。不要またはガイドと矛盾していると思われる場合は、お知らせください（または、それらのガイドラインをガイドに含めるべきかどうかについても）。

「いいね！」 2
9

この前の2つは気に入りました。ガイドの趣旨に沿っていますし、ガイド自体に含める価値があります。今すぐ追加します。

「いいね！」 1
10

他の言語のドキュメントにラベルを付けるためのフラグは例外だと想定しています。

「いいね！」 1
11

慣用句を避けることと共に、私はドキュメントで短縮形を使うことを常に避けてきました。非英語圏/非西洋圏の読者にとって理解しにくくなると思ったからです。英語は奇妙な言語です。

moreover？

どこかの時点で、私たち（おそらく私）はサイト設定を参照するためにインラインコードを使用し始めました。例えば、「discourse connect サイト設定を有効にする」といった具合です。それは正しいアプローチかもしれませんが、少し開発者っぽい感じがします。

Discourseサイトを参照するために、一貫したプレースホルダー名を使用する価値があるかもしれません。discourse.example.com のようなものでしょうか？ ここには、Discourseサイトを sitename.com と参照しているドキュメントがいくつかあります。それは本当に私を混乱させました。

一般的なライティングのアドバイスとして、ターゲットオーディエンスの一員になったつもりで、自分が書いたものを読んでみてください。（短縮形がトリッキーであることがわかります）オーディエンスの事前知識に関する自分の仮定が妥当かどうかを確認してください。

ドキュメントトピックが私に割り当てられなくなったことをどれほど感謝していても、チームのすべてのドキュメントトピックの作成者としてDiscourseを使用するのは、少し冷たい感じがします。

私が再び執筆を楽しむようになったのは、あなたが書いているものに自分自身を少しでも反映させる方法を探すというアドバイスでした。それは、あなたの声のトーン、あなたの趣味、何でも構いません…それは、ここで推奨されていることとは正反対のことです。

「いいね！」 6
12

やあ、サイモン！ :blob_wave:

この件については様子を見ようと思っていましたが、私も同じように、短縮形を避けるようにしています。

ハハ、ええ…ドキュメントであのような言葉を一切使わないようにします。さもないと、私の :face_with_monocle: が露呈してしまいます。

確かに：Example Domains

これが私が議論するためにここに来たポイントです！ :smiley:

この件については、多くの議論がありましたが、これがスタイルガイドにデフォルトで含まれているのを見て嬉しかったです。

これが重要だと考える理由は次のとおりです。ドキュメントの作成は、コミュニティの可能な限り多くのメンバー、特にDiscourseチームのメンバーにとってアクセスしやすいものである必要があります。

Discourseはソーシャルなディスカッションソフトウェアです。そして、一部のドキュメントは実際には継続的な会話です。コミュニティのメンバーをオンボーディングする方法の実践を共有する場合、そのトピックの「所有者」として提示されたいので、質問に答えたり、主題を拡張したりできます。

一方で、顧客が私たちがまだ説明できていない機能について尋ねてきた場合、スタイルガイドを使用して有用で一般的なドキュメントを作成できることを望みます。これは、トピックの所有者であることが公開により大きな慣性を与えると私が感じていることです。

また、Discourse以外でドキュメントを作成する場合（統合やコードコメントからの生成など）、ドキュメントユーザーがいる方が実装の詳細としてはおそらく簡単です。 :thinking:

このガイドが、人々が自分の声や個性を注入することを止めることはないと思います。そして議論をホストすることも。しかし、そうでなければドキュメントを作成しないであろうより多くの人々がドキュメント作成の実践に参加するのに役立つことを願っています（そしてその後、彼らに個人的になるように促すことができます！） :smiley:

「いいね！」 3
13

ローカライズされたドキュメントをネイティブで処理できるようになるまで、タイトルにフラグを付けるのが最も実用的な方法であり、このガイドラインの妥当な例外だと思います。

この種のことは、どちらの意見や好みも異なると思いますが、このスタイルガイドでは、業界で認められている標準を採用します。繰り返しになりますが、GoogleとMicrosoftのガイドラインは、一般的な短縮形を使用した方が良いという点で一致しています。

とはいえ、否定的な短縮形（「can’t」など）を使用すると、英語話者でない人にとって理解が難しくなる可能性があるという意見もいくつか読みました。この点についてはさらに調査し、必要に応じてスタイルガイドを更新します。

その例は削除しました！ :smile:

はい、それは非常に一般的です（Discourseだけでなく）、しかし、それが正確ではないことには同意します。引用符を使用する方が良いでしょう。そのため、スタイルガイドで明示することにしました。

それは素晴らしい点です。スタイルガイドに追加します！

このフィードバックありがとうございます！ @maikiは上記でいくつかの良い点を挙げており、私はそこで彼が言っていることに同意します。それに加えて、公式ドキュメントの作成者を@Discourseにした理由の1つは、特に初めてドキュメントにアクセスする読者に対して、より権威があると感じてもらうためです。これも、そもそもスタイルガイド全体を作成した動機です。

ドキュメントを作成する人は、誰でも自分の個性を文章に注入できますし、個々のドキュメントトピックに関する議論はなくなるわけではないので、そこは常にパーソナルなものにする良い場所です。

これらのフィードバックはすべて非常に感謝しています :slight_smile:

「いいね！」 2
14

ガイドのメタブロックに関する部分についてです。上記のガイドによると、Docトピックにはメタブロックが必要ですが、すべてのトピックにメタブロックがあるわけではありません[1]し、常に一貫しているわけでもありません。以下に、いくつか見つけたガイドからの例を挙げます。

個人的には「全ユーザー」が好きです。

フィードバックを集める前に、トピックのメタブロックを変更したくありませんでした :smiley:

  1. トピックの文脈によるかもしれません？ ↩︎

「いいね！」 4
15

すべての @Discourse ドキュメントは作業中で、最終的にはすべて対応される予定です (:crossed_fingers:）。しかし、一貫性のなさについては良い点ですね。どれに落ち着くかは分かりませんが、一つを選んでそれに固執するようにします。:slight_smile:

「いいね！」 4
16

さらに、新しい情報ブロックが含まれているものがあれば、それらは「フェーズ1」を通過し、レビュー段階に入っていることを意味します。そのため、もしそれらを読んで「それは正しくない」または「情報が不足している」と感じ、フィードバックを残すのに十分な寛大さがあれば、投稿にあなたの考えを追加してください。:heart: :slight_smile:

「いいね！」 5
17

一番上の必須ユーザーレベル情報は、どのような目的で使用されていますか？文書が自分に関連しているかどうかについての情報を提供してくれると思ったのですが、「私はxxxではないので、関連性がない」と判断して読むことができるからです。
しかし、例えばTL3未満のユーザーでもウィキを編集できるため、他の人にとっても関連性があるため、異なる方法で使用されているようです。

「いいね！」 3
18

@Moin、ご指摘ありがとうございます。そのトピックは、必要なユーザーレベルを修正するように更新されました。

その情報が何のためのものかについてのあなたの理解は正しいです。ドキュメントで説明されているアクションを実行できるユーザーレベルまたはタイプを示す必要があります。

「いいね！」 1