⭐️

【Polaris和訳】Content/Help documentation

2021/10/29に公開

Shopify

polaris

tech

この記事について

この記事は、Polaris/Content/Help documentationの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

ヘルプドキュメント

アプリやその他の整合性を構築した後、ヘルプドキュメントを書くことで販売者にその使い方を示すことができます。

これらのガイドラインは、私たちがShopify Help Centerのヘルプドキュメントを書いた経験に基づいています。これらのガイドラインは、Shopify の販売者を教育し、強化するという同じ目的のためのものです。

あなたのアプリやチャンネルにヘルプドキュメントへのリンクを含めるには、フッターのヘルプコンポーネントを使用します。

オーディエンスのための計画

ヘルプドキュメントの書き方は、対象者のタイプや期待する内容によって変える必要があります。時間をかけてオーディエンスのために計画してください。

対象者のタイプ

ヘルプドキュメントは、対象となる読者に合わせて書きます。どのようなドキュメントであっても、幅広い範囲の Shopify ユーザーを読者として想定することができます。

将来のユーザー

まだサインアップしていない、おそらくフリートライアル中のユーザー

初心者ユーザー

登録はしたが、オンライン販売の経験はないかもしれない。
コンピューターリテラシーが低い可能性がある
Shopify のコンセプトやワークフローに慣れていない

経験豊富で自信のあるユーザー

Shopify を使ったことがある
基本的なコンセプトとワークフローに精通している
コンピュータに自信がある
指導を受けながらいくつかのカスタマイズを試すことができる

高度なテクニカルユーザー

経験豊富で自信がある
豊富なコンピュータの経験
リスクを冒してでも実験したい
経験豊富な問題解決者
フォーラムやヘルプドキュメントを利用したセルフサービス

ユーザーの期待

これらの異なるユーザーは、同じドキュメントに対して異なる期待を持っています。それがどのようなものかを見てみましょう。

検討中のユーザー

クイックスタートガイド
概念的な概要

初心者のユーザー

丁寧な説明
わかりやすいステップバイステップの説明
概念の概要
用語の定義
チュートリアル
状況に応じたヘルプ

経験豊富で自信のあるユーザー

明確なステップ・バイ・ステップの説明
概念的な説明
用語の定義
難易度の高いチュートリアル
状況に応じたヘルプ

高度な技術を必要とするユーザー

手続きの説明（ポイントを押さえた説明でも可
コードフラグメント
情報源へのポインター

これは、オーディエンスに当てはまる様々なユーザーを想像するための一つの方法に過ぎません。ユーザーのスキルレベルをどのように想像しても、ドキュメントの目的は同じです。そのためには、異なるスキルレベル、異なる学習スタイル、異なるワークフローに対応できるように情報を提供することが必要です。

見出しを使ってドキュメントを整理する

ヘルプドキュメントを読む人は、さまざまな期待を持って、さまざまな使用環境で訪れます。たとえば、次のような場合です。

ある人は、サードパーティのアプリを自分の管理者に接続するために、長くて複数の段階のある設定プロセスを行っているかもしれません。
ある人は、タブレットを使って Shopify POS の詳細をチェックし、自分のカフェで使えるかどうかを確認しているかもしれません。
またある人は、子供を学校に迎えに行く前の 30 分で、自分の店頭を素早く編集しようとしているかもしれません。

このような様々なケースにおいて、読者は見つけやすく、使いやすく、関連性のある、つまり整理されたドキュメントを必要としています。

効果的な見出し

効果的な見出しは、文書のどのセクションが読者の現在のタスクに最も関連しているかを明確にします（見つけやすさ）。また、ひとつのタスクから次のタスクに移る際にも、見出しによって進捗状況を把握することができます（ユーザビリティ）。

低レベルの見出し

一般的に、文書の階層の中で見出しの位置が低いほど、そのトーンに柔軟性があります。例えば、低レベルの見出しは、より長く、より具体的であったり、よりフォーマルであったりします。

見出しの階層

文書全体で見出しの階層を維持し、見出しレベルをスキップしないようにします。例えば、H1 から H2 へ、そして H3 へ......というように。これにより、読者は、特定のワークフローに沿って読んでいるのか、あるいは単にスキャンしているのかにかかわらず、自分がドキュメントのどこにいるのかを知ることができます。

ヒント

ページやトピックレベルの見出しには、短いジェランド（ing-word）ベースの文を使います。

ドキュメント内のタスクベースの見出しには、動詞のステム／命令形を使用します。

見出しでは代名詞や冠詞を避け、短くまとめます。

見出しの中では、長い名詞の羅列は避けましょう。

重要な記述は見出しの先頭に近い位置に置くと、すぐに目を通すことができます。例えば、"How to "や "To "で見出しを始めないようにします。

同じレベルの見出しの間では、平行な文法構造を保つようにしてください。

ほとんどの場合、見出しは質問ではなく文であるべきです。質問形式の見出しは、FAQ（よくある質問）や、特定の機能を扱う低レベルの見出しにとっておいてください。

すべての見出しには文語を使用し、最後にピリオドは入れないでください。インターフェイスの要素やボタンは、Shopify の管理画面で表示されるようにフォーマットし、大文字を使用してください。

リストや見出しなど、あらゆる場面で並列構造を用いることで、理解や想起を促します。

タスクを文書化する

タスク指向であること

ほとんどのヘルプドキュメントはタスク指向です。タスクを完了するために必要なステップを読者に案内するように設計されています。最良のドキュメントは、読者がタスクを素早く完了できるようにすることで、時間を節約します。情報の見せ方は、その情報が読者にとってどれだけ役に立つかに大きく影響します。

導入を使う

ほとんどの場合、ドキュメントは手順の説明から始めるべきではありません。その代わりに、導入部のコメントで背景を説明したり、トピックに関する重要なコンセプトを定義したりします。読者が説明書に目を通す前に、どのような情報が必要なのかを判断します。これは、ドキュメントのサブセクションにも当てはまります。

番号付きのステップを使う

読者がどのようにタスクを考えているかを反映した方法で説明書を分割します。タスクの各部分には、番号付きのステップを使用します。これにより、読者の注意を引くことができ、タスクを完了するためにヘルプドキュメントと Shopify の間を切り替えることが容易になります。

ワークフローの最初から始める

長いドキュメントの中の主要なタスクの説明は、独立していることを確認してください。もし、あるタスクの説明が、前のタスクが終わったところで突然始まると、その時点から始めた読者は、ワークフローを理解するのに苦労するでしょう。それぞれのタスクは、そのタスクを完了するために必要なワークフローの最初から文書化しましょう。

短いリストを使う

一般的には、長いリストよりも短いリスト（番号付きのステップや箇条書き）の方が読みやすいと言われています。10 個以上の項目が必要なタスクやリストがある場合は、2 つ以上のリストに分け、それぞれに小見出しをつけます。

タスクを実行可能にする

製品に何ができるかではなく、製品で何ができるかをユーザーに伝えましょう。つまり、製品の機能ではなく、ユーザーの行動を中心にドキュメントを構成するのです。読者は仕様書を読むためにいるのではなく、ビジネスを継続させるためにいるのです。

一般的に、複数のアクションを 1 つの番号のついたステップにまとめることは避けてください。各ステップには、1 つまたは 2 つのユーザーアクションのみを含めるようにしてください。

タスクの中で、ユーザーに何かを「見つける」「探す」という指示を出すのは避けましょう。

決められた選択肢の中から何かを選んでもらう場合（リストやドロップダウンメニューなど）には「select」という動作語を使い、より自由な選択をしてもらう場合（「どんなお店を開きたいか選んでください」など）には「choose」を使います。

読者の選択に言及する際には、一貫した表現を使用してください。また、"If you would like to "や "If you wish to "のようなフォーマルな表現ではなく、最も直接的な "If you want to "を使いましょう。

より直接的な "want "の代わりに、"desired "を使うことは避けましょう。

条件文の構成

条件付きのケースでは、ステップを「if」で始めることで、読み手が文全体を読んで、その条件が自分には当てはまらないことを知る必要がなくなります。読み手が条件と結果を特定できるように、"then "を追加するとよいでしょう。

アクションの結果を明確にする

行動の結果は、タスクと同じステップで表示し、読者がフローのどこにいるのかを明確にします。

アクションと結果を同じステップに

ユーザーのアクションの結果について言及する必要がある場合は、そのアクションを説明するのと同じ番号のステップで行います（別の番号のステップを使用しないでください）。一般的には、結果が意外なものでない限り、結果の記述は省略します。

タスクの順序を強調するために、前のステップに言及する

以前のステップを参照することで、ステップの順序を確認することができます。

一連のステップの中での進捗状況については、"When you've "または "After you've "というフレーズを使用します。Once you've "の使用は避けてください。

タスク間の進捗については、"Now that you've "または "After you've"(前のアクションやステップを参照)でセクションを始めます。

重要なタスクには "make sure "や "confirm "を使う

読み手に何かを確認してもらうときに使います。

関連する重要なタスクが残っている場合には、"Make sure "を使います（"check that "や "verify that "の代わりに）。
"Confirm "は、読者がすでに何かをするように言われていて、それを思い出させるような場合に使います。

ヒント

指示の場合は、動詞の命令形を使います。

未来形は、実際に未来に言及するケースに限定する。

スクリーンショットを使ってわかりやすく

スクリーンショットは、視覚障害者が複雑なタスクを理解するのに役立ち、文書化しているタスクにコンテキストを追加します。賢く利用しましょう。

複雑なタスクにはスクリーンショットを使う

一般的に、タスクのすべてのステップを説明するためにスクリーンショットを使用することはありません。スクリーンショットは、インターフェイスが複雑な場合に使うようにしましょう。

スクリーンショットの余白を均等にする

スクリーンショットのある部分を強調する際には、読者に注目してもらいたい部分の周囲に同じだけの余白を設けるようにしましょう。

ワークフロー内の画像を統一する

ドキュメント内のスクリーンショットの詳細を統一することで、ストーリー性を持たせることができます。例えば、1 つの順序に沿って、スクリーンショットから次のスクリーンショットまで詳細を同じにすることができます。

ドキュメントで教える

ドキュメントは教育の機会でもあります。文脈を構築し、指示を明確にして、学習を促すことが重要です。

次のステップへのリンク

次のステップへのリンクを提供しましょう。読者のプロフィールやフィードバックに基づいて次のステップを選択する。

学習を促す

読者にもっと知りたいと思わせる。ドキュメントの導入部で、その機能の利点を説明する。

最初のタスクを容易にする

可能であれば、読者に "早い者勝ち "を与える。タスクの最初のステップや 2 つのステップを短く、簡単にします。

文脈を作る

現在のタスクを、読者の幅広い知識に結びつけてください：Shopify の他の部分、店舗構築のプロセス、さらにはビジネス構築のプロセスなどです。

同じページで情報を繰り返さないようにする

ほとんどの場合、1 つのページで情報を繰り返さないようにします。読み手が気づくように、重要なポイントを繰り返す必要があるかもしれません。例えば、ドキュメントの導入部にある警告を、一連の指示の中で繰り返すような場合です。

適切なトーンの使用

読み手が置かれている状況や、ドキュメントを読んでいるときに感じたり考えたりしていることを考えてみましょう。このような観点から、どのようなトーンを適用すべきかを選ぶことができます。

説明的なトーン

多くの人は、ドキュメントを読むことに時間をかけたくありません。必要なことだけを学び、次に進みたいのです。ドキュメントに書かれている言葉は、短く、要点を押さえ、タスク指向である必要があります。だからといって、文章が簡潔で乾いたものである必要はありません。

明るめのトーン

一般的に、ドキュメントは軽いトーンで始めることができます。

インフォーマルなトーン

タスクを紹介する際には、インフォーマルなトーンにすることで、読者を引き込み、文脈を提供し、先に進ませることができます。また、サブタスクを紹介する際には、よりインフォーマルなトーンを使うことで、読者に指示からの解放感を与えることができます。

ダイレクトなトーン

行動やタスクについては、より直接的なトーンを目指します。短縮形（can't, it's など）を使って指示と結果を結びつけることで、親しみやすいトーンを保つことができます。

ヒント

短縮形を使う。

読者やユーザーを "you "と呼びます。

以下のようなことがないように、トーンを抑えてください。

インフォーマルで親しみやすい印象を与えようとして、恩着せがましい言い方、仲良しこよしの言い方、元気な言い方、子供っぽい言い方、その他不適切な言い方をすること。
口語表現、ジョーク、皮肉、専門用語、スラングなど。あまりにも文化的に特殊なものは避けてください。
ユーザーが立ち止まったり、躊躇したりするような表現は、明示的な意図がない限り避けてください。

アクティブボイスの使用

一般的に、受動態よりもフォーマルに聞こえない能動態をできるだけ使用してください。つまり、商人が何をしているかではなく、商人が何をしているかを書くのです。しかし、受動態が能動態よりも自然に聞こえる場合には、受動態を使用してください（「publish」や「assign」などの動詞や「discount」などの名詞の場合など）。

読みやすさの向上

文章は流れるように書くことが大切です。物事に変化をつけたり、組み合わせや分離のタイミングを知ることで、プロスペクションが向上します。流れのある文章を読むことは、読者の理解力を高めます。

途切れがちな文章を避ける

副詞、接続詞、前置詞などを積極的に使うことで、ぎこちない文章を避けることができます。

文章構造を変える

特に長い段落では、文の構成を変えてみましょう。To x, do y "のような構造のフレーズを 2 つ以上連続して使わないようにしましょう。可能であれば、短い宣言文を加えて、文章を区切りましょう。

複雑な文章の分割

複雑な文章は、接続詞（単語や単語のグループをつなぐ言葉）を使って区切ります。

Shopify アプリのご紹介

Discussion

ログインするとコメントできます