ヘルプページの書き方
ヘルプページを書くうえでの基本的な考え方と表記ルールをまとめました。
ドラフトを自分でレビューする際は「チェックリスト」を活用してください。
また、このページで記載していない表記ルールは、プロダクトデザインにおける基本的な考え方、用字用語、UIテキストに準拠します。
ユーザーが確実に目的を達成できる状態を目指しましょう
ヘルプページの役割は、ユーザーが目的を達成するサポートです。
情報を簡潔明瞭に伝えて、ユーザーが操作につまずかないようにしましょう。
不要な情報や曖昧な表現は目的達成の妨げとなるため、削除や言い換えを検討しましょう。
チェックリスト
情報を取捨選択しましょう
- 必要な情報を漏れなく記載する
- 不要な情報を記載しない
- 本文への追加情報に用いる囲み要素の多用を避ける
情報を適切に配置しましょう
- 先に知っておくべき情報から順番に配置する
- 関連する情報は近くに配置する
- 見出しや箇条書きを適切に使う
ヘルプページの並び順や構成の考え方については、ヘルプページの構成を参照してください。
正確かつ簡潔明瞭に説明しましょう
- ユーザーの状況やアプリケーションの状態を意識して、タイトルや見出しをつける
- 「どこをどのように操作するのか」を詳しく記載する
- 機能の名前やUIテキストは正確に記載する
- 似たような機能や概念が同時に出てくる場合は、呼び方を区別する
- 注意事項や付加要素を記載するための括弧（カッコ）書きの使用を避ける
- 「〇〇してしまった」など、主観の入った表現を使わない
- 「〇〇から」「〇〇より」など、複数の意味として読解できる表現を使わない
- 「主に」「基本的に」など、例外の存在をほのめかす表現を使わない
- 「ここで」「それを」など、曖昧な指示語を使わない
表記ルールに従いましょう
- 文体は敬体を使って「ですます」調で表記する
- 英語・数字・記号は半角で表記する
- 設定項目名、タブ名、操作ボタン名、選択肢は、
［］で囲んで太字で表記する - 画面名は
［］で囲わずに表記する - ユーザーが入力する文字列は
「」で囲む - 書類名や法律などの固有名詞は
「」で囲む - 強調したい単語は厳選し、太字で表記する
- 他のヘルプページへのリンクには、ページタイトルを記載する
- 別ドメインの自社ページへのリンクには、ページタイトルとサイト名を記載する
- 出典を示す場合は、ページタイトルとサイト名を記載する
- 外部リンクはできるだけ使わない
スクリーンショット掲載の考え方に従いましょう
- アクセシビリティの観点から、スクリーンショットはできるだけ使わず、テキストで説明する
- スクリーンショットを使う場合は、ユーザーに注目させたい部分を囲みや矢印をつけて強調する
- スクリーンショットを使う場合は、ユーザーの操作に必要ない部分を取り除く
詳細は「ヘルプページ用の画像」のスクリーンショット掲載の考え方を確認してください。
具体的な書き方のヒント
情報を取捨選択しましょう
必要な情報を漏れなく記載する
ユーザーの目的を整理して、その達成に必要な情報を精査しましょう。
また、ユーザーの疑問点を想定して、先回りして回答を記載しましょう。
自己レビューの際は、ユーザーが目的を達成するうえで、不足している情報や曖昧な記載がないかを確認してください。
不要な情報を記載しない
ヘルプページの役割は、仕様をすべて伝えることではありません。
必要以上の情報は、ユーザー自身に情報の取捨選択を委ねることになり、かえってユーザーを惑わせてしまいます。ユーザーが知らなくても済む操作や、意思決定に影響しない情報は割愛しましょう。
なお、本筋とは関係ないものの、ユーザーにとって有益な情報は、ページを分けて記載したり、囲み要素として本文と区別したりしましょう。
本文への追加情報に用いる囲み要素の多用を避ける
囲みを多用すると、本文でユーザーに伝えたい要点がぼやけてしまいます。
囲みには、必要な情報を目立たせる役割があります。一方、本文からは分断されるため、本筋とのつながりが伝わりづらくなることがあります。
囲みのガイドラインを参照して、本当に囲みが必要かどうかを精査しましょう。
特に、以下の点に注意してください。
- 読み飛ばしてもユーザーの操作に影響しない情報を「注意点」として記載しない
- 本筋と直接関係があり、ユーザーに読み飛ばしてほしくない情報を「Tips」として記載しない
- 囲みを使う必要がない場合は、本文に統合する
- 同じ種類の囲みが連続する場合は、1つの囲みに統合する
情報を適切に配置しましょう
先に知っておくべき情報から順番に配置する
読まれる順番を意識して、ユーザーが先に知っておくべき情報を前に配置しましょう。
例えば、特定の機能について説明する場合は、その機能で何ができるのかを先に記載してから、設定方法などの詳細を記載しましょう。
操作の前に知っておくべき注意事項は、操作手順の前に記載します。操作手順のあとに記載すると、ユーザーが注意事項に気づくのが遅れて、操作ミスにつながる可能性があります。
関連する情報は近くに配置する
関連する情報は、その関係が読み取りやすいよう近くに配置しましょう。
例えば、特定の操作に関する注意事項がある場合は、操作手順の近くに記載します。
注意事項をページの冒頭でまとめて記載すると、操作と注意事項の紐づきがわかりづらくなり、読み飛ばされる可能性があります。
見出しや箇条書きを適切に使う
ページ内の情報構造がわかりやすいように、構成を工夫しましょう。
例えば、改行がなかったり、手順や具体例など複数の要素が分類されずに書かれていたりすると、ユーザーが要点を把握しづらくなります。
見出しで情報を切り分けたり、箇条書きで整理したりして、情報のまとまりを把握しやすくしましょう。
表は見やすくメンテナンスしやすい形式で使う
表の列の幅が狭く、縦に長くなりすぎて、見づらくならないように気をつけましょう。
Tipsや補足などは、できるだけ表外に記載しないようにします。情報の対応関係が一目でわかるように、補足の列を設けるようにしましょう。
正確かつ簡潔明瞭に説明しましょう
ユーザーの状況やアプリケーションの状態を意識して、タイトルや見出しをつける
タイトルや見出しは、その記事を必要としているユーザーが「何がしたいか」、アプリケーションが「どんな状態か」を意識して記載します。
例えば、アプリケーション上のデフォルトの設定が「従業員が変更できる」の場合、「変更できないようにする」手段を伝えるときは、「従業員による変更を制限する」などのタイトルにします。
「どこをどのように操作するのか」を詳しく記載する
操作方法を説明する場合は「どこをどのように操作するのか」を詳しく記載します。
操作するボタンやリンクの画面上の位置、およびボタンやリンクのテキストを明記すると、操作場所を特定しやすくなります。「画面右上」など表示位置だけを記載しても、どこを右上とするかはユーザーによって認知が異なる場合があるため、具体的なラベル名も明示しましょう。
また、操作内容は「設定します」「編集します」などと曖昧に記載せず、目的語を明記して具体的に説明しましょう。
例
悪い例
- 画面右上のメニュー内のボタンを押します。
- 書類の提出について設定します。
良い例
- 画面右上の［〇〇］メニュー内にある［△△］を押します。
- 書類の提出を必須とするかどうかを設定します。
機能の名前やUIテキストは正確に記載する
機能名やUIテキストは、画面上に記載されているとおりに記載します。
独自の表現で言い換えると、画面のどの部分を指すのかわかりづらくなるため、正確に記載してください。
似たような機能や概念が同時に出てくる場合は、呼び方を区別する
同じページ内に、似たような機能や概念が複数登場する場合は、読み手が混同しないように呼び方を区別しましょう。
例えば「Microsoft Wordで作成した雇用契約書の書類テンプレート」と「SmartHRで作成した雇用契約書のテンプレート」が同時に出てくると、「テンプレート」という言葉が重複し、どちらの書類を指すのか判断しづらくなります。
この場合、いずれかの「テンプレート」を他の方法で言い換えると、どちらの書類を指すのか理解しやすくなります。
例
悪い例
- Microsoft Wordで作成したテンプレートをお持ちの場合、レイアウトをSmartHRの書類テンプレートに登録できます。
良い例
- Microsoft Wordで作成した契約書のひな形をお持ちの場合、レイアウトをSmartHRの書類テンプレートに登録できます。
注意事項や付加要素を記載するための括弧（カッコ）書きの使用を避ける
文中に括弧を多用すると、読み手の注意が散漫となり、要点が伝わりづらくなります。
補足説明をする場合は、括弧内に記載せずに一文追加することを検討しましょう。
例
悪い例
- 〇〇できます。（〇〇は対象外です）
- 〇〇をダウンロードします。（ダウンロードの進捗状況は〇〇画面で確認できます）
良い例
- 〇〇できます。ただし、〇〇は対象外です。
- 〇〇をダウンロードします。ダウンロードの進捗状況は〇〇画面で確認できます。
「〇〇してしまった」など、主観の入った表現を使わない
ユーザーに客観的に情報を伝え、不要な先入観を与えないように、書き手の主観を入れないようにしましょう。
例えば「重要な」「大切な」「〇〇と思います」といった表現は、書き手の主観を含んでいます。読み手であるユーザーが、書き手と同じように感じるとは限りません。
特に「〇〇してしまった」「残念ながら」など、ネガティブな印象の言葉は避けてください。
例外として「よくある質問」の見出しには「〇〇してしまった」という表現を使えます。よくある質問の書き方には、「見出しは口語体で、ユーザーからの質問のように表現する」というルールがあります。ユーザーの発言として自然であれば、「〇〇してしまった」という表現を使っても構いません。
例
悪い例
- エラーが表示されてしまった場合は〜
- スピードが改善しました。
良い例
- エラーが表示された場合は〜
- スピードが速くなりました。
「〇〇から」「〇〇より」など、複数の意味として読解できる表現を使わない
複数の意味を持つ表現を使うと、読み手に意図した内容が伝わらない可能性があります。一意に理解できる表現に言い換えましょう。
例えば、あるメニュー内の追加ボタンを選ぶ操作は「メニューから追加ボタンを選択」や「メニューより追加ボタンを選択」と表現できます。
この場合の「〇〇から」「〇〇より」は動作の起点を指す意味で使われています。
しかし、「〇〇から」には「AからBができる」など構成要素の意味もあります。
また、「〇〇より」には「AよりBの方が大きい」など比較の意味もあります。
複数の意味がある場合、一読しただけでは意味が解釈しづらいため、「〇〇内の」や「〇〇にある」など、より伝わりやすい言葉に言い換えましょう。
例
悪い例
- ［共通設定］より［権限］を押します。
- 〇〇すると表示される画面から［△△］を押します。
良い例
- ［共通設定］にある［権限］を押します。
- 〇〇すると表示される画面にある［△△］を押します。
「主に」「基本的に」など、例外の存在をほのめかす表現を使わない
「主に」「基本的に」などの表現を使うと、例外や複数のパターンがあるように読めてしまいます。
基本パターンと例外があることを示したい場合は、基本パターンを簡潔に記載したあとで、例外や注意事項を明記しましょう。
また、複数のパターンがある場合は、できるだけ網羅的に記載しましょう。
パターンが2つの場合は、「Aの場合とBの場合があります」などと記載します。
パターンが3つ以上ある場合は、「以下の原因が考えられます」などと前置きしてから、箇条書きや小見出しを使って詳細を説明しましょう。
例
悪い例
- 基本的に〇〇できます。
- 主な原因として、〇〇が考えられます。
良い例
- 〇〇できます。ただし、△△は対象外です。
- 以下の原因が考えられます。（以下、原因を列記する）
「ここで」「それを」など、曖昧な指示語を使わない
「ここで」「それを」など、「こそあど言葉」と呼ばれる指示語を使った場合、文脈を理解していないと、何を指しているのか判断できません。
画面名やボタン名を明記して、何を指しているかが確実に伝わるようにしましょう。
表記・掲載ルールに従いましょう
文体は敬体を使って「ですます」調で表記する
文体は敬体を使って、「〇〇です」「〇〇ます」という形で表記します。
英数字・記号は半角で表記する
英数字・記号は半角で表記します。前後に半角スペースを入れる必要はありません。
ただし、手順番号やよくある質問の表記においては、ピリオドのあとに半角スペースを入れます。
例：1. ［アプリ一覧］の［共通設定］>［全般設定］を押す
例：Q. パスワードを忘れてしまったら？／A. パスワードをリセットして、再設定してください
UIテキストは［］で囲んで太字で表記する
画面名・項目名・ボタン名など、画面上に表示されているUIテキストは、全角の［］で囲んで太字で表記します。
また、「+」や「▼」などの記号が含まれるボタン名は、記号を含めて表記します。
例：［+カスタム項目グループを追加］
ユーザーが入力する文字列は「」で囲む
ユーザーが入力する文字列は、地の文と区別しやすいように「」で囲みます。
さらに強調したい場合は、太字で表記しても構いません。
例：扶養家族ありの場合は、「001」と入力してください。
書類名や法律などの固有名詞は「」で囲む
書類名や法律などの固有名詞は、地の文と区別しやすいように「」で囲みます。
さらに強調したい場合は、太字で表記しても構いません。
なお、一覧表や箇条書きで書類名を羅列する場合は、「」で囲む必要はありません。
例：「雇用保険被保険者離職証明書」
強調したい単語は厳選し、太字で表記する
単語を強調したり、読みやすくしたりしたい場合は、太字で表記します。
ただし、太字の表記が多すぎると、強調したい箇所がわかりづらくなるため、太字にする箇所は厳選しましょう。
他のヘルプページへのリンクには、ページタイトルを記載する
ヘルプページから他のヘルプページにリンクさせる場合、リンクテキストには該当のページタイトルを記載します。
例：詳しくは、電子申請機能を利用するための準備を参照してください。
別ドメインの自社ページへのリンクには、ページタイトルとサイト名を記載する
ヘルプページから、smarthr.jpやSmartHR Mag.などの別ドメインのページにリンクさせる場合は、「ページタイトル｜サイト名」という形で記載します。
例：詳しくは、SmartHRを活用した、社会保険資格取得届の効率的な電子申請方法｜SmartHR Mag.を参照してください。
出典を示す場合は、ページタイトルとサイト名を記載する
画像や法令などの出典を示す場合は、「出典：画像名｜サイト名」または「出典：ページタイトル｜サイト名」という形で記載します。
外部リンクはできるだけ使わない
他社のサービスについて説明する場合、外部リンクで他社サイトに誘導することがあります。
しかし、リンク先のURLが変更された際に更新が漏れてしまい、デッドリンクになる危険性があります。
ページの情報を最新の状態に保ちやすくするため、むやみに外部リンクを使わないようにしましょう。
代替案として、「詳細は◯◯社のサイトを参照してください」などと記載し、リンクを掲載しない方法も検討してください。この場合、ユーザーが他社サイトを見つけやすいように、検索キーワードとなる単語を文中に含めましょう。
やむを得ず外部リンクを使う場合は、「ページタイトル｜サイト名」という形で記載します。
ヘルプページのタイプ別の考え方とパターン
ヘルプページのタイプ別に作成時の考え方とライティングパターンをまとめています。