ナレッジベースの貢献者として、あなたは 5 億人のユーザーを助けるために言葉を使います。これは大きな仕事です。ユーザーは世界中からナレッジベースを訪れ、簡単な解決策を期待していますが、私たちは私たちのボイスで彼らを喜ばせたいとも思っています。どうすればよいのでしょうか？ここに、私たちの調査で得られたいくつかの事柄があります。

トーン

ブランドを意識して書きましょう。Mozilla はユーザーの選択を大切にしています。私たちは自由と柔軟性を信じています。私たちはプライバシーとセキュリティを重視しています。私たちは、共通の価値観を共有する世界中の貢献者がいる、コミュニティ主導の非営利団体です。

記事を書くたびにこのストーリーを強調する必要はありません。これは、機能を説明するときに心に留めておくべきことです。

ライティングスタイル

一般的で、技術に詳しくない読者に向けて書きましょう。

私たちの記事は、上級ユーザーだけでなく、誰もが使えるようにしたいと考えています。これは、コンピューターの技術や専門用語に非常に詳しい読者ではなく、一般の読者に向けて書くことを意味します。あなたが書いている相手は、ステップバイステップの手順なしでは設定を変更したり、ツールバーのボタンを追加したりする方法を知らないと想定してください。また、彼らが既定のアプリケーションやオペレーティングシステムの設定を何も変更していないと想定すべきです。

要約すると、以下のガイドラインに従うべきです:

1. 簡潔に。 人々は簡単な解決策を求めてナレッジベースを訪れます。彼らはツールの内部の仕組みには興味がないかもしれません – 彼らが知りたいのは、問題を解決するために 自分たち が何をすべきかということです。言葉を削ってみましょう。より少ない言葉でどれだけ伝えられるか試してみてください。詩のようです！
2. 明確に。 専門用語を避けましょう。具体的に書きましょう。タイトルや記事には、読者が使うであろう言葉を使いましょう。あなたの 13 歳の甥が理解できないなら、彼が理解できるように書き直しましょう。より広範なガイドについては、次のセクションを参照してください。
3. フレンドリーで、楽しく、共感的に。(要するに、人間らしく。) そうです、ユーザーはサポートに楽しさを期待して来ません。だからこそ、これが強力なのです。少しのユーモアでユーザーの一日を明るくしましょう。しかし、楽しい比喩や表現を使って明確さを犠牲にしないように注意してください。このバランスの取り方がわからない場合は、単に率直な手順を書き、導入部や結論でトーンを使いましょう。
4. ストーリーを語る。 始まり、中間、終わりを持たせましょう。しかし、小説を書かないでください (ガイドライン #1 を参照)。
   • 始まり: これは読者に文脈を与えます。この記事は何についてで、なぜ気にする必要があるのか？簡潔にしましょう。
   • 中間: 手順はここに書きます。これは「どうすればこれをできるのか？」に答えるべきです。
   • 終わり: 記事や機能に次のステップはありますか？もっと学びたい場合に次にどこへ行くべきかを読者に伝えましょう。

より包括的なガイドラインについては、次のセクションを読んでください。

ライティングスタイル (包括的)

• 会話的なライティングスタイル – 対面で誰かと話すときのように、インフォーマルで能動的なスタイルを使いましょう。
• ユーモアと感情 – ユーモアを使うのは素晴らしいことですが、ローカライズするのが難しい、あるいは不可能な場合があります。驚きや「知らなかった！/発見した！」のような感情は、含めやすいかもしれません。
• 複数の学習スタイル – 学校と同じように、人々は異なる方法で学びます。また、誰もが同じコンテンツが複数の方法で表現されているのを見ることから利益を得ます。
• 反復 – 異なるメディアで異なる方法で何かを説明するとき、あなたは明らかにそれを反復しており、これは人々に重要なことを覚えてもらうためのもう一つの良い方法です。
• 画像と動画 – テキストと共に画像や動画を使用することは、対面で助けることに次ぐ最良の方法であるだけでなく、複数の学習スタイルと反復を簡単に含める方法でもあります。しかし、画像が多すぎると記事のローカライズが難しくなる可能性があるため、ステップやコンセプトに役立つ場合にのみ画像を追加するようにしてください。例えば、ボタンをクリックするステップでは、そのボタンのダイアログボックスのスクリーンショットを追加する代わりに、「OK をクリックします」と言うことができます。
• アクティビティ – 特にチュートリアルでは、人々に何か役立つことを達成させることが良いことです。手順を読んでプロセスを理解することも一つですが、人々に試してみることを思い出させ、可能にすることも多くの場合役立ちます。

記事の種類

ナレッジベースの記事に一貫したコンテンツタイプを使用することには、ナビゲーションの容易さ、明確さと整理の向上、さらにコンテンツをより効果的に作成するのに役立つなど、多くの利点があります。私たちは、外部のナレッジベース記事を、それぞれが特定の目的を果たす 4 つのタイプに分類するように移行しています:

• 概要 (About): これらの記事は「〜とは何か？」という質問に対応し、読者がトピックを理解するのに役立つ重要な情報を提供します。
• ハウツー (How-to): これらの記事は「〜する方法は？」という質問に答えることに焦点を当て、読者が特定の目標や手順を達成するために必要なステップを案内します。
• トラブルシューティング (Troubleshooting): これらの記事は、問題解決に関連する「〜する方法は？」という質問に対応することで、ユーザーが製品、サービス、または機能で遭遇する可能性のある一般的な問題を特定、診断、解決するのを支援します。
• よくある質問 (FAQ): これらの記事は、他の個別の KB 記事には収まらない可能性のある、単一のトピックに関するよくある質問への簡潔な回答を含んでおり、一般的な問い合わせに対するクイックリファレンスを提供します。

効果的で説明的なタイトルから始める

巧みに作られたタイトルは単なるラベルではありません。それはユーザーがあなたの KB 記事と最初に接触する点です。良いタイトルは、読者の注意を引くだけでなく、記事の内容の簡潔で有益なプレビューとしても機能するべきです。SUMO のタイトルを作成する際は、以下を考慮してください:

• 明確さと説明性: 記事の内容とユーザーが検索しているものとを一致させます。簡潔でありながら、ユーザー中心にしましょう。
• キーワードの包含: 関連するキーワードを組み込んで、検索エンジンの可視性を向上させ、ユーザーがあなたの記事を見つけやすくします。
• 簡潔さ: 十分な情報を提供しつつ、タイトルを短く保ちます。短いタイトルはしばしばよりユーザーフレンドリーです。タイトルを約 60 文字に保つようにしてください。
• アクション指向: 該当する場合、ユーザーが問題を解決したり目標を達成したりするために何ができるかを示すために、アクション動詞を使用します。タイトルがアクション指向であり続けるように、動名詞 (「ing」で終わる単語) の使用を避けてください。「〜する方法」を含むタイトルの使用を避けてください。

良い導入部を書く

タイトルや目次と並んで、導入部はユーザーが正しい場所にいるかどうかを判断するのに役立つものです。

• 「概要」記事の場合: コンセプトのテキストによる概要または定義を提供し、ユーザーがなぜそれを気にするべきかに焦点を当てます。
• 「ハウツー」記事の場合: タスクのテキストによる概要または定義を提供し、タスクの重要性や利点に焦点を当てます。
• 「トラブルシューティング」記事の場合: ユーザーが遭遇する可能性のある特定の問題や症状を説明します。可能な限り専門用語を避け、明確で簡潔な言葉で書きます。

良い導入部は通常、良い検索結果の要約として機能することを心に留めておいてください。多くの場合、それを「検索結果の要約」フィールドにコピーするだけで完了です。

記事を効果的に整理する

ここでの一般的な考え方は、ほとんどの人が必要とする情報を上部に置きながら、単純なものから複雑なものへとスキルを構築しようとすることです。したがって、単純で一般的な解決策は、通常、複雑なまたはエッジケースの解決策の前に来るべきです。

ステップバイステップの手順を分かりやすくする

ステップバイステップの手順を書く際に心に留めておくべき主なことは、タスクを完了するために必要なすべてのアクションを含めるように注意することです。例えば、次のステップに進むために設定を選択した後に OK をクリックする必要がある場合、そのステップの一部として「OK」をクリックすることを含めるようにしてください。 考慮すべき追加事項:

• 結果を達成するには常に複数の方法があります。可能な場合は グラフィカルユーザーインターフェイス とメニューを使用して、常に最もユーザーフレンドリーな方法を選ぶべきです。
• ユーザーインターフェイスへのアクセス方法を説明する際は、完全な文を使用してください。
• 指示を与える際には、期待される結果を含めてください (例: 「OK」をクリックすると、ウィンドウが閉じます。)。

可読性

テキストは読みやすくなくてはなりません。そのためには、以下を行う必要があります:

• 記事を小見出し付きの小さな論理的/意味的なブロックに分割する。
• 番号付きリストや箇条書きリストを使用する。
• 短い、または比較的短い文を書く。
• 長い段落を書くのを避ける。

テキストの量に制限はありません。資料が多ければ多いほど良いですが、人為的に拡張するべきではありません。有用で、価値があり、必要な情報のみを提供してください。

サードパーティ製ソフトウェアの外部ドキュメントへのリンク方法

オペレーティングシステムや外部アプリケーションなどのサードパーティ製ソフトウェア内でのアクションを含む記事を作成または更新する際には、ユーザーに正確で信頼性の高い情報を提供することが重要です。しかし、私たちの記事にこのソフトウェアの直接的な手順を含めることには、課題が生じる可能性があります:

• すぐに古くなる情報: サードパーティ製ソフトウェアの更新により、私たちの手順が時代遅れになり、ユーザーを混乱させたり誤解させたりする可能性があります。
• リソース集約的: 複数の外部プラットフォームの手順を継続的に監視および更新するには、多大な労力とリソースが必要となり、それは現実的ではないかもしれません。

ベストプラクティス

リソースを圧迫することなく、ユーザーが最も信頼性が高く最新の情報を受け取れるようにするために、以下のベストプラクティスに従ってください:

• 公式リソースへのリンク: 手順がサードパーティ製ソフトウェアに関わる場合は常に、ソフトウェアメーカーが提供する公式ドキュメントやヘルプ記事を見つけてください。私たちの記事に直接手順を書き出す代わりに、これらのリソースにリンクしてください。
• 文脈の提供: ユーザーを外部ページに誘導する理由を簡潔に説明してください (例: 「システム設定を調整するための最新かつ最も正確な手順については、公式の [software name] サポートページを参照してください」)。
• リンクの定期的な確認: サードパーティの手順のメンテナンスを減らすことを目指していますが、外部リンクがまだ有効であることを定期的に確認することは依然として重要です。リンクが古くなったり壊れたりしていることに気づいた場合は、公式ドキュメントへの更新されたリンクを探し、改訂を提出してください。
• 外部コンテンツに関する免責事項: ユーザーを外部リンクに誘導する際には、彼らが SUMO を離れること、そして私たちが外部サイトのコンテンツに責任を負わないことを明確にしてください。簡単な免責事項や注意書きで十分です (例: 「このリンクをたどると、Mozilla が運営していない外部のウェブサイトにリダイレクトされます」)。

例

Mac のシステムレベルの設定変更に依存する Firefox の機能を設定する記事を書いていると想像してください。記事に直接手順を概説する代わりに、次のように書くことができます:

macOS でのシステム環境設定の調整に関する最新の手順については、このガイド にアクセスして、Apple の公式サポートドキュメントを参照してください。そのリンクをたどると、Mozilla が運営していない外部のウェブサイトにリダイレクトされることに注意してください。

これにより、ソースから直接、最新の指示に従っていることが保証されます。

技術的なガイドライン

• 実際に新しい記事を作成する方法を学ぶには、新しいナレッジベース記事を作成する を参照してください。
• 既存の記事を編集する方法を学ぶには、ナレッジベースの記事を編集する を参照してください。
• ナレッジベースがどのように機能するかの概要については、About the Knowledge Base を参照してください。
• 記事のドキュメントの完全なリストについては、ナレッジベースを改善するには を参照してください。

タイトル

• タイトルの長さ: Google の検索結果ページには最大 60 文字が表示されます。必要であればタイトルをこれより長くすることもできますが、重要なキーワードが最初の 60 文字に含まれていることを確認してください。
• 大文字の使用: タイトルの最初の単語、および 固有名詞 と名前は、すべての主要な単語ではなく、大文字で始める必要があります。「センテンス」スタイルであり、「ヘッドライン」スタイルではない を使用してください。(同じことが見出しのタイトルにも適用されます。大文字の使用に関する他のルールについては、以下の スタイルガイドと表記ルール セクションを参照してください。) ただし、リダイレクトが作成されず、そこへリンクしている記事内の wiki リンクが壊れることになるため (bug 1969540)、他のタイトルの変更を行わない限り、大文字の使用を変更するために既存の記事のタイトルを編集しないでください。
• 記事のタイトルにコロンを使用しないでください。その記事への wiki リンクの作成が妨げられます (bug 749835)。また、記事のタイトルに余分なスペースがないことを確認してください。これも wiki リンクが機能しなくなる原因となります。
• 記事の命名方法を多様化するようにしてください。すべてのタイトルで同じ単語やフレーズを使用しないでください。例えば、常に「方法」で記事を始めたり、「ホームページの設定」のような「ing」で終わるタスク名の使用を避けたりしないでください。
• 説明全体をタイトルに入れる必要はないことを覚えておいてください。要約を使用して、記事の内容に関する追加情報をユーザーに提供できます。

スラッグ

新しい記事を作成してタイトルを入力すると、SUMO は自動的に スラッグ (記事の URL の末尾にある kb/ の後の部分) を作成します。レビュー担当者は既存の記事のタイトルを編集できますが、手動で変更されない限り、スラッグは同じままです (これは仕様です)。スラッグには 50 文字の制限があります。スペースはダッシュとして表示されます。スラッグはタイトルと一貫しているべきですが、スペースの制約が厳しいため、同じである必要はありません。

スラッグを修正する

自動生成されたスラッグの末尾を必ず確認してください。単語が途中で切れたり、ダッシュで終わったりすることがあります。そのような点を修正してください。

既存の記事のスラッグを更新する

既存の記事のタイトルを更新する際は、新しいタイトルが既存のスラッグと一致しなくなるような大幅な変更を表す場合を除き、現在のスラッグを変更しないでください。スラッグを一貫させることで、リンク切れを避け、SEO の価値を維持するのに役立ちます。

カテゴリー、製品、トピック

ほとんどの場合、記事は「ハウツー」または「トラブルシューティング」のいずれかのカテゴリーに属します。時折、「貢献する方法」の記事 (この記事のような) など、他のカテゴリーの記事を書くこともあります。記事の履歴ページにカテゴリーが表示されます。

記事はまた、少なくとも 1 つの製品に「関連」しています。また、1 つのメインの「トピック」と、任意で「サブトピック」に属します。

キーワード

記事のキーワードフィールドは、SUMO の検索結果を改善するために使用できます。ただし、誤用は実際に検索に悪影響を与える可能性があるため、特定の状況下でのみ使用すべきです。キーワードを使用する必要はほとんどありません。詳細については、When and how to use keywords to improve an article's search ranking を参照してください。

良い検索結果の要約を書く

記事の要約は、タイトルとともに、ユーザーが記事が自分の質問に答えるかどうかを判断するのに役立ちます。私たちはこれを「ユーザーの信頼」と呼び、クリックスルー率に直接影響します。検索結果リストのトップに正しい記事を表示したとしても、ユーザーが記事にクリックスルーするためには、検索クエリと私たちが表示する結果との間で精神的なつながりを作る必要があります。

ハウツー記事の要約には、記事でカバーされているトピックを含めるべきです。トラブルシューティング記事では、症状を含めるように努めるべきです。さらに、要約は以下のガイドラインに従うべきです:

• 短く、要点を押さえる。求人広告を覚えていますか？そのように書いてください。検索エンジンは 140 文字を超える部分を切り捨てることがあります。より長い要約を使用する場合は、重要な情報を冒頭に置いてください。注: 内部検索の制限が 160 文字であるため、要約が 140 文字に達すると、KB ソフトウェアは残り 20 文字と表示します。
• wiki マークアップを使用しない。
• すべての要約で「この記事では説明します」を使用しない。可能な場合は変化させてください。考慮すべき他のフレーズ:
  • 〜を紹介します
  • 〜を説明します
  • このページでは説明します
  • この記事では記述します
  • 〜を学びましょう

ステップ数

ユーザーをプロセスを通じて案内する際には、順序付きリスト (番号付きリスト) を検討してください。一般的に、総ステップ数を 6〜7 の範囲に保つように努めるのが良い習慣です。

並列構造

書くすべてのステップで同じ言い回しや言葉のパターンを使用してください。並列構造は、物事を明確で分かりやすくするため、KB 記事において重要です。類似の要素が一貫した形式を持つと、ユーザーはタスクをよりスムーズに理解し、完了できます。この構造は指示を簡素化し、間違いを減らし、情報が効果的に伝わることを保証します。

例:

1. Firefox の終了時に履歴を消去する を見つけます。これが選択されている場合:
   1. Settings… ボタンをクリックします。
   2. フォームと検索の履歴 が選択されて いない ことを確認します。
   3. OK をクリックします。

方向を示す手がかり

方向を示す手がかりとは、ユーザーが特定の行動を取る必要があるユーザーインターフェイス内の特定の場所や位置を案内する参照や指標のことです。これらの手がかりは、ユーザーがソフトウェア、アプリケーション、ウェブサイトをより効果的にナビゲートし、操作するのに役立ちます。通常、「右上の角に」、「左側のメニューに」、「検索バーの下に」といったフレーズが含まれ、ユーザーにどこで行動を見つけて実行するかを明確に伝えます。

KB 記事の指示では、行動の 前 に方向を示す手がかりを提供するようにしてください。例えば、「ボタンをクリックしてください」と言う代わりに、「右上の角にあるボタンをクリックしてください」と使用します。この形式は、ユーザーがインターフェイス内で行動を簡単に見つけて実行するのに役立ちます。

スタイルガイドと表記ルール

前述のように、書くときは能動的で会話的なスタイルを使用すべきです。「ユーザーのブックマークが失われた場合」のような言い方を避け、「ブックマークを失った場合」のように言ってください。以下は、サポート記事を書く際に遭遇する可能性のある、その他の一般的なスタイルと表記の問題です: 常に Mozilla のインターフェイスに表示される通りの用語を使用してください。 例:

• Plugins にはハイフンが ありません。
• Add-ons にはハイフンが あります。
• Home page は 2 語です。

一般的なコンピューター用語:

• ウェブサイト は 1 語です。ウェブページ は 2 語です。
• Log in と log out は動詞です。例: 「ウェブサイトにログインする (Log in to the website)。」 sign in と sign out にも同じことが当てはまります。「log into」や「sign into」は使用しないでください。
• Login と logout は名詞です (通常は形容詞として使用されます)。例: 「ログインボタンをクリックする (Click the login button)。」
• e-mail の代わりに email を使用してください。
• CD-ROM の複数形は CD-ROMs です。

mozilla.org および firefox.com へのリンクにはロケールを含めないでください:

• https://www.mozilla.org/en-US/ の代わりに https://www.mozilla.org/ を使用してください。
• https://www.firefox.com/en-US/ の代わりに https://www.firefox.com/ を使用してください。

文中にリンクを組み込む場合:

• リンクテキストとして「ここをクリック」や「ここ」を使用しないでください。
  • 良い例: アカウント設定に移動して、サブスクリプションをキャンセルしてください。
  • 悪い例: ここをクリックして、サブスクリプションをキャンセルしてください。

以下の項目を大文字で始めてください:

• 固有名詞 と名前 (ブランド名、製品名、機能名を含む)
• 完全な文の最初の単語
• 通常小文字でない限り、略語や頭字語の文字
• 番号付きリストや箇条書きリストの最初の単語
• キーボードのキーの名前
• コロンに続く完全な文の最初の単語
• 見出しやタイトルの最初の単語

Mozilla accounts:

• Mozilla accounts の「a」は、ヘッドラインケーシングを使用している他のナビゲーション項目と一緒に含まれているナビゲーション項目を除き、常に小文字です。
• 常に「sign in」と「sign out」を使用してください。
• 動詞形では、文法的に正しくするために「sign in to your account」(「sign into」ではない) を使用してください。
• 「Sign in with Mozilla」も使用できます。
• 「Sign」は常に動詞として使用すべきです。名詞として使用する場合は、「login」を使用してください。
• 新しいアカウントを作成するための行動喚起として「sign up」を使用してください。

KB 記事で Mozilla accounts を参照する方法の詳細については、Editorial guidelines for Mozilla accounts を参照してください。

「i.e.」と「e.g.」 を使用しないでください. これらのラテン語の略語は人々を混乱させる可能性があります。明確にするために、何かを別の方法で説明したい場合は i.e. の代わりに「つまり」や「言い換えると」を使用してください。例を挙げたい場合は e.g. の代わりに「例えば」や「〜など」を使用してください。

項目のリストで シリアルコンマ を使用しないでください。 例えば、「拡張機能、テーマ、プラグイン (Extensions, themes and plugins)」(シリアルコンマなし) を使用し、「拡張機能、テーマ、そしてプラグイン (Extensions, themes, and plugins)」は使用しないでください。

一般的に理解されていると考えられる頭字語を使用してください。 例:

• HTTP
• USB
• URL

製品のバージョン、エラーコード、キー、ボタンに現れる 数字 は、スペルアウトされません。

指示は能動態で書いてください。 能動態と現在形は指示を簡素化し、従いやすくし、迅速な行動を促します。例:

「更新するために Firefox を再起動してください」ではなく「Firefox は再起動される必要があります」。

パスや検索でのバックスラッシュ (\) とフォワードスラッシュ (/) は、混乱を避けるためにスペルアウトしてください。

例: 「画像への一部のパス名にはバックスラッシュ (\\) が含まれています」。

キーボードショートカット キーボードショートカットまたはショートカットの組み合わせの最初の文字を大文字にしてください: Ctrl + Shift + C または Command + Shift + C。

スラングとイディオム を使用しないでください. 私たちの記事はすべて多くの異なる言語に翻訳されるため、英語を母国語としない人々によって読まれ、翻訳されます。スラングやイディオムは曖昧である可能性があり、読者を混乱させ、翻訳をより困難にする可能性があります。

項目に適切な wiki マークアップを追加することで実現できる、多くの項目のための特別な視覚スタイルがあります。 最も一般的なスタイルについては、マークアップ早見表 を参照してください。

特定のバージョンの Firefox や特定のオペレーティングシステム向けの情報を対象とすることができる、特別な wiki マークアップ – {for} – があります。 例えば、Windows を実行している人々と macOS を使用している人々に、それぞれ異なる一連の指示を表示できます (詳細は How to use "For" tags を参照)。