Thunderbird のナレッジベース記事の書き方

記事を執筆、編集するとき、多くの競合する事柄のバランスを取る必要があります。完全かつ簡潔に、事実に基づき、そして同時に人を引きつけるようにしたいものです。これは決して簡単なことではありません。ここでは、そのバランスを取る作業を少し簡単にするためのガイドラインをいくつか紹介します。また、これは wiki ですから、もし間違えてもいつでも修正できます。 __TOC__ ==誰のために記事を書くのか？== 私たちは、Thunderbird ヘルプがすべての Thunderbird ユーザーにとって利用しやすいものであることを望んでいます。これは、コンピューターの技術や専門用語に非常に詳しい人ではなく、一般の読者に向けて書くことを意味します。あなたが記事を書いている相手は、段階的な手順なしでは設定の変更やツールバーボタンの追加方法を知らないと想定してください。また、Thunderbird やオペレーティングシステムの既定の設定を何も変更していないと想定すべきです。 ==良いタイトルを選ぶ== 記事のタイトルを選ぶときは、人々が検索したり閲覧したりする内容、つまり、直接あなたに尋ねるかもしれない質問に合わせるようにしたいものです。以下に、選ぶべきタイトルの種類の例をいくつか示します: *チュートリアルやハウツー記事の場合: どうすればこの結果を達成できますか？ (例: メールを送信するには？) *リファレンス記事の場合: 機能名とは何ですか？ (例: プラグインとは？) *トラブルシューティング記事の場合: これが私の抱えている問題です (例: Thunderbird の起動に時間がかかる) ==文章を魅力的にするテクニック== Thunderbird ヘルプは、メールクライアントアプリケーションである Thunderbird の操作に関する技術情報の集積場所です。このドキュメントには、Thunderbird のさまざまな機能、トラブルシューティングの手順、一般的な問題の解決方法が記載されています。ドキュメントには、各ページの検索機能を使ってアクセスできます。 ヘルプ記事を書く際には、以下のテクニックとガイドラインを使用してください。これらのガイドラインは、ユーザーがソフトウェアの使い方を学んだり、抱えている特定の問題を解決したりするのに役立ちます。 *'''会話的な文体''' – 直接誰かに話しかけるような、くだけた能動的なスタイルを使用してください。 *'''ユーモアと感情''' – ユーモアや感情は最小限に抑えてください。適切な場合には、ユーザーがタスクを達成するのを助けるために、励みになるヒントやアドバイスを記事に含めてください。ユーモアやその他の感情を使うことはユーザーの助けにならず、かえってイライラさせてしまう可能性があります。 *'''多様な学習スタイル''' – 学校と同じように、人々の学習方法は異なります。また、同じ内容が複数の方法で表現されているのを見ることは、誰にとっても有益です。 *'''反復''' – 概念やタスクを異なる方法で説明するとき、あなたはそれを繰り返しているだけでなく、ユーザーが重要なアイデアを記憶するのを助けています。 *'''画像と動画''' – テキストと共に画像や動画を使って物事を説明することは、直接手助けすることに次ぐ最良の方法であるだけでなく、多様な学習スタイルと反復を容易に取り入れる方法でもあります。 *'''実践''' – 特にチュートリアルでは、人々に何か役立つことを達成してもらうのが良いでしょう。手順を読んでプロセスを理解することも一つですが、実際に試してみるように人々に促すことがしばしば役立ちます。 [[Master Password]] の記事は、これらのテクニックを使った良い記事の例です。 ==良い導入部を書く== タイトルや目次と並んで、導入部は人々が自分が正しい場所にいるかどうかを素早く判断するために使うものです。 *チュートリアルやハウツー記事の場合: 何を学べるかを簡潔に要約してください。 *リファレンス記事の場合: 機能について簡潔に説明してください。 *トラブルシューティング記事の場合: 問題とその症状を簡潔に要約してください。 良い導入部は、通常、良い検索結果の要約として役立ちます。多くの場合、それを「検索結果の要約」フィールドにコピーするだけで完了です。 ==記事を構成する== ここでの基本的な考え方は、ほとんどの人が必要とする情報を上部に置きながら、スキルを簡単なものから複雑なものへと構築していくことです。したがって、単純で一般的な解決策は、通常、複雑な、または特殊なケースの解決策の前に置かれます。 ==段階的な手順を分かりやすくする== 段階的な手順を書く際に心に留めておくべき主なことは、タスクを完了するために必要なすべてのアクションを注意深く含めることです。例えば、次のステップに進むために設定を選択した後に「OK」をクリックする必要がある場合は、そのステップの一部として OK をクリックすることを含めるようにしてください。 考慮すべき追加事項: *結果を達成する方法は常に複数あります。私たちは常に最もユーザーフレンドリーな方法、つまり、可能な限りグラフィカルユーザーインターフェースとメニューを使用する方法を選ぶべきです。 *ユーザーインターフェースへのアクセス方法を説明する際は、完全な文章を使用してください。 *指示を与える際には、期待される結果を含めてください (例: OK をクリックするとウィンドウが閉じます)。 以下は [[Master Password]] の記事からの例で、括弧内にいくつかの説明が付いています。 <br><br>'''マスターパスワードの変更または削除''' <br> (見出し — この手順で達成されること) マスターパスワードはいつでも変更または削除できます: (文脈 - 全体像を示す — なぜこれを行うのか) # Thunderbird ウィンドウ上部の {menu Tools} メニューをクリックし、{menu Options...} を選択します。 # {menu Security} アイコンをクリックします。 # {menu Passwords} タブをクリックします。 # {button Change Master Password} をクリックします。 # 現在のパスワードを入力して、変更する権限があることを確認します。 #* マスターパスワードを忘れた場合は、[[Forgot my master password]] を参照してください。 # 新しいマスターパスワードを 2 回入力します。 #* マスターパスワードを削除するには、新しいマスターパスワードのフィールドを空のままにします。 # 変更されたマスターパスワードを確定するには、{button OK} をクリックします。 # マスターパスワードが変更されました。 == SUMO スタイルガイド == 先ほど話したように、書くときは能動的で会話的なスタイルを使用すべきです。したがって、「ユーザーのブックマークが失われた場合...」のような言い方を避け、「ブックマークを失った場合...」のように言うべきです。サポート記事を書く際に遭遇する可能性のある、その他の一般的なスタイルに関する問題を以下に示します: '''常に Thunderbird のインターフェースに表示される通りの用語を使用してください。''' 例: *Plugins にはハイフンがありません。 *Add-ons にはハイフンがあります。 *Home page は 2 つの単語です。 '''一般的なコンピューター用語:''' *internet は小文字です。 *Website は 1 つの単語です。 *Log in と log out は動詞です。例: 「ウェブサイトにログインする (Log in to the website)。」 *Login と logout は名詞です (通常は形容詞として使用されます)。例: 「ログインボタンをクリックする (Click the login button)。」 *e-mail の代わりに email を使用してください。 *CD-ROM の複数形は CD-ROMs です。 '''ウェブサイトへのリンクにロケールを含めないでください:''' *https://addons.mozilla.org/en-US/thunderbird/ の代わりに https://addons.mozilla.org/thunderbird/ を使用してください。 '''以下の項目は大文字で始めてください:''' *固有名詞 *完全な文の最初の単語 *通常小文字でない限り、略語や頭字語の文字 *番号付きリストや箇条書きリストの最初の単語 *キーボードのキーの名前 *コロンに続く完全な文の最初の単語 *見出しやタイトルの最初の単語 '''見出しとセクション''' 私たちの wiki は HTML5 を使用して表示され、<nowiki><section></nowiki> 要素を利用しています。関連するコンテンツを <nowiki><section></nowiki> 要素で囲むことができます。これが見出しにとって意味することは、各セクションが h1 レベルの見出しで始まる独自のアウトラインを持つことができるということです。 '''明確にするため、i.e. や e.g. の使用は避けてください。どうしても使用する必要がある場合は、[http://theoatmeal.com/comics/ie こちらにその使い方に関するすばらしい解説] があります。''' '''いくつかの項目には特別な視覚スタイルがあり、項目を適切な wiki マークアップで囲むことで実現できます (完全なリストは [http://support.mozilla.com/en-US/kb/markup-chart Firefox と Thunderbird のナレッジベースのマークアップ一覧] を参照してください)。''' *{note}注{/note} *{warning}警告{/warning} *<code>コード</code> *{filepath File names} や {filepath file/paths} *{key Ctrl+T} のようなキーボードショートカット *メニューパス – {menu Thunderbird} *{button ボタン} '''特定のバージョンの Thunderbird や特定のオペレーティングシステムを対象とした情報を表示できる、<nowiki>{</nowiki>for<nowiki>}</nowiki> という特別な wiki マークアップがあります。''' 例えば、Windows を実行している人々と Mac OS X を使用している人々に、それぞれ異なる一連の手順を表示できます ([[markup|詳細は、マークアップガイドの "SHOWFOR" のセクションを参照してください]])。

記事を執筆、編集するとき、多くの競合する事柄のバランスを取る必要があります。完全かつ簡潔に、事実に基づき、そして同時に人を引きつけるようにしたいものです。これは決して簡単なことではありません。ここでは、そのバランスを取る作業を少し簡単にするためのガイドラインをいくつか紹介します。また、これは wiki ですから、もし間違えてもいつでも修正できます。

誰のために記事を書くのか？

私たちは、Thunderbird ヘルプがすべての Thunderbird ユーザーにとって利用しやすいものであることを望んでいます。これは、コンピューターの技術や専門用語に非常に詳しい人ではなく、一般の読者に向けて書くことを意味します。あなたが記事を書いている相手は、段階的な手順なしでは設定の変更やツールバーボタンの追加方法を知らないと想定してください。また、Thunderbird やオペレーティングシステムの既定の設定を何も変更していないと想定すべきです。

良いタイトルを選ぶ

記事のタイトルを選ぶときは、人々が検索したり閲覧したりする内容、つまり、直接あなたに尋ねるかもしれない質問に合わせるようにしたいものです。以下に、選ぶべきタイトルの種類の例をいくつか示します:

• チュートリアルやハウツー記事の場合: どうすればこの結果を達成できますか？ (例: メールを送信するには？)
• リファレンス記事の場合: 機能名とは何ですか？ (例: プラグインとは？)
• トラブルシューティング記事の場合: これが私の抱えている問題です (例: Thunderbird の起動に時間がかかる)

文章を魅力的にするテクニック

Thunderbird ヘルプは、メールクライアントアプリケーションである Thunderbird の操作に関する技術情報の集積場所です。このドキュメントには、Thunderbird のさまざまな機能、トラブルシューティングの手順、一般的な問題の解決方法が記載されています。ドキュメントには、各ページの検索機能を使ってアクセスできます。

ヘルプ記事を書く際には、以下のテクニックとガイドラインを使用してください。これらのガイドラインは、ユーザーがソフトウェアの使い方を学んだり、抱えている特定の問題を解決したりするのに役立ちます。

• 会話的な文体 – 直接誰かに話しかけるような、くだけた能動的なスタイルを使用してください。
• ユーモアと感情 – ユーモアや感情は最小限に抑えてください。適切な場合には、ユーザーがタスクを達成するのを助けるために、励みになるヒントやアドバイスを記事に含めてください。ユーモアやその他の感情を使うことはユーザーの助けにならず、かえってイライラさせてしまう可能性があります。
• 多様な学習スタイル – 学校と同じように、人々の学習方法は異なります。また、同じ内容が複数の方法で表現されているのを見ることは、誰にとっても有益です。
• 反復 – 概念やタスクを異なる方法で説明するとき、あなたはそれを繰り返しているだけでなく、ユーザーが重要なアイデアを記憶するのを助けています。
• 画像と動画 – テキストと共に画像や動画を使って物事を説明することは、直接手助けすることに次ぐ最良の方法であるだけでなく、多様な学習スタイルと反復を容易に取り入れる方法でもあります。
• 実践 – 特にチュートリアルでは、人々に何か役立つことを達成してもらうのが良いでしょう。手順を読んでプロセスを理解することも一つですが、実際に試してみるように人々に促すことがしばしば役立ちます。

Thunderbird のパスワードをマスターパスワードで保護する の記事は、これらのテクニックを使った良い記事の例です。

良い導入部を書く

タイトルや目次と並んで、導入部は人々が自分が正しい場所にいるかどうかを素早く判断するために使うものです。

• チュートリアルやハウツー記事の場合: 何を学べるかを簡潔に要約してください。
• リファレンス記事の場合: 機能について簡潔に説明してください。
• トラブルシューティング記事の場合: 問題とその症状を簡潔に要約してください。

良い導入部は、通常、良い検索結果の要約として役立ちます。多くの場合、それを「検索結果の要約」フィールドにコピーするだけで完了です。

記事を構成する

ここでの基本的な考え方は、ほとんどの人が必要とする情報を上部に置きながら、スキルを簡単なものから複雑なものへと構築していくことです。したがって、単純で一般的な解決策は、通常、複雑な、または特殊なケースの解決策の前に置かれます。

段階的な手順を分かりやすくする

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

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

以下は Thunderbird のパスワードをマスターパスワードで保護する の記事からの例で、括弧内にいくつかの説明が付いています。

マスターパスワードの変更または削除
(見出し — この手順で達成されること)

マスターパスワードはいつでも変更または削除できます:

(文脈 - 全体像を示す — なぜこれを行うのか)

1. Thunderbird ウィンドウ上部の Tools メニューをクリックし、Options... を選択します。
2. Security アイコンをクリックします。
3. Passwords タブをクリックします。
4. Change Master Password をクリックします。
5. 現在のパスワードを入力して、変更する権限があることを確認します。
   • マスターパスワードを忘れた場合は、マスターパスワードを忘れた場合にリセットするには を参照してください。
6. 新しいマスターパスワードを 2 回入力します。
   • マスターパスワードを削除するには、新しいマスターパスワードのフィールドを空のままにします。
7. 変更されたマスターパスワードを確定するには、OK をクリックします。
8. マスターパスワードが変更されました。

SUMO スタイルガイド

先ほど話したように、書くときは能動的で会話的なスタイルを使用すべきです。したがって、「ユーザーのブックマークが失われた場合...」のような言い方を避け、「ブックマークを失った場合...」のように言うべきです。サポート記事を書く際に遭遇する可能性のある、その他の一般的なスタイルに関する問題を以下に示します:

常に Thunderbird のインターフェースに表示される通りの用語を使用してください。 例:

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

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

• internet は小文字です。
• Website は 1 つの単語です。
• Log in と log out は動詞です。例: 「ウェブサイトにログインする (Log in to the website)。」
• Login と logout は名詞です (通常は形容詞として使用されます)。例: 「ログインボタンをクリックする (Click the login button)。」
• e-mail の代わりに email を使用してください。
• CD-ROM の複数形は CD-ROMs です。

ウェブサイトへのリンクにロケールを含めないでください:

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

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

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

見出しとセクション 私たちの wiki は HTML5 を使用して表示され、<section> 要素を利用しています。関連するコンテンツを <section> 要素で囲むことができます。これが見出しにとって意味することは、各セクションが h1 レベルの見出しで始まる独自のアウトラインを持つことができるということです。

明確にするため、i.e. や e.g. の使用は避けてください。どうしても使用する必要がある場合は、こちらにその使い方に関するすばらしい解説 があります。

いくつかの項目には特別な視覚スタイルがあり、項目を適切な wiki マークアップで囲むことで実現できます (完全なリストは Firefox と Thunderbird のナレッジベースのマークアップ一覧 を参照してください)。

• 注
• 警告
• コード
• File names や file/paths
• Ctrl + T のようなキーボードショートカット
• メニューパス – Thunderbird
• ボタン

特定のバージョンの Thunderbird や特定のオペレーティングシステムを対象とした情報を表示できる、{for} という特別な wiki マークアップがあります。 例えば、Windows を実行している人々と Mac OS X を使用している人々に、それぞれ異なる一連の手順を表示できます (詳細は、マークアップガイドの "SHOWFOR" のセクションを参照してください)。