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

トーン

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

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

ライティングスタイル

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

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

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

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

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

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

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

記事の種類

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

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

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

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

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

良い導入部を書く

タイトルと目次と共に、導入部はユーザーが正しい場所にいるかどうかを判断するのに役立ちます。

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

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

記事を効果的に整理する

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

段階的な指示を分かりやすくする

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

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

読みやすさ

テキストは読みやすいものでなければなりません。そのためには、次のことを行う必要があります:

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

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

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

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

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

ベストプラクティス

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

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

例

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

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

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

技術的なガイドライン

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

タイトル

• タイトルの長さ: Google の検索結果ページには最大 60 文字が表示されます。必要であればタイトルはこれより長くてもかまいませんが、重要なキーワードが最初の 60 文字に含まれていることを確認してください。
• 大文字表記: タイトルの最初の単語と、固有名詞 や名前は、すべての主要な単語ではなく、大文字にする必要があります。「文スタイル」を使用し、「見出しスタイル」は使用しないでください。 (同じことが見出しのタイトルにも適用されます。大文字表記に関する他のルールについては、以下の スタイルガイドとコピーのルール セクションを参照してください。) ただし、他のタイトルの変更を行わない限り、大文字表記を変更するために既存の記事のタイトルを編集しないでください。リダイレクトが作成されず、そこにリンクしている記事内の壊れた Wiki リンクが発生するためです (バグ 1969540)。
• 記事のタイトルにコロンを使用しないでください。その記事への Wiki リンクの作成が妨げられます (バグ 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 文字を超える部分を切り捨てることがあります。より長い要約を使用する場合は、重要な情報を冒頭に置いてください。注: KB ソフトウェアは、要約が 140 文字に達すると残り 20 文字と表示します。これは、内部検索の制限が 160 文字であるためです。
• Wiki マークアップを使用しない。
• すべての要約で「この記事では説明します」を使用しない。可能な場合は変化を持たせてください。考慮すべき他のフレーズ:
  • 〜を紹介します
  • 〜を説明します
  • このページでは説明します
  • この記事では記述します
  • 〜を学びましょう

ステップの数

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

パラレル構造

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

例:

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

方向指示

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

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

スタイルガイドとコピーのルール

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

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

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

• ウェブサイト は 1 語です。ウェブページ は 2 語です。
• Log in と log out は動詞です。例: 「ウェブサイトにログインする。」sign in と sign out にも同じことが当てはまります。「log into」や「sign into」は使用しないでください。
• Login と logout は名詞です (通常は形容詞として使用されます)。例: 「ログインボタンをクリックする。」
• 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. の代わりに「例えば」や「〜など」を使用してください。

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

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

• HTTP
• USB
• URL

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

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

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

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

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

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

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

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

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