良いチュートリアルの書き方

できるだけガイド単体で読めるようにする。ユーザーが必要とする全ての行動を1つのページにまとめて書く。
必要な手順数はユーザーが必要とするものに絞る。たくさんのステップからなる手順は、情報量が多すぎてユーザーは複雑だと感じる。また長い手順によりミスが起きやすくなり、必要な保守も多くなりがちです。
長い説明を避ける、数行の説明文や適切な配置の画像は効果的だが、付加的なコンテンツがあまりに多いとユーザーを怯ませてしまいがちです。良い方法は、一枚の標準的なモニター画面で2つ以上の手順をユーザーが見られるように書くこと。
チュートリアルに10個以上の手順が含まれていたらユースケースが長すぎる。
ドキュメントの目的と、読み手が達成できることをドキュメントに明確に書いておく。タイトルと最初の段落の両方に、ドキュメントの目的と、読み手が達成できることを書いておくと良い。
手順の最後には、正常に完了できたかを確認する方法を書いておきましょう。

参考

https://www.amazon.co.jp

Google Cloudのチュートリアルスタイルガイド

文章のスタイル

軽快な文章にする: チュートリアルでは、有用で豊富な情報を提供しますが、あまり形式張らないようにします。
ユーザーの呼称: 二人称代名詞を使用します（使用する表現: ユーザーは、あなたの、使用しない表現: 私たちは、私は、私たちの、など）
原因と結果を説明する: ステップを実行するようユーザーに求めるときは、アクションの背後にある推論と期待される結果を説明します。
目標を絞る: チュートリアルのコンテンツを書く前に、ユーザーが達成する明確な目標を設定します。この目標を念頭に置いてチュートリアルを作成します。

おすすめの方法

内容を短くする: ユーザーに一度に提供できる情報量は限られています。目を通すことが困難で垂直スクロールが必要な大量のテキストを避けてください。たやすく把握できる量の情報を提供することが望まれます。
- 1 ページあたりのステップは 5 つまで、コードスニペットは 3 つまでにすることを心掛けます。
- 段落は 5 行以下とするのが理想的で、単一のコンセプトを扱うようにします。
- コードとターミナルブロックは、一度に読み取れる小さいサイズにします。
  - なるべく 10 行以下にします。
  - 水平スクロールを減らすために、1 行につき 80 文字以下になるようにします。
  - ユーザーが一括コピー実行を行わないように、複数コマンドのコードブロックは避けます。
前置きのページ: チュートリアルは前置きから始めます。
- 期待を抱かせる: ユーザーがこのチュートリアルを完了することから得られるメリットを簡単に説明します。
- 推定作業時間: ユーザーがチュートリアルに費やす時間をおおまかに見積もります。15 分以内に終了できるチュートリアルの作成を心掛けます。チュートリアルが長い場合（つまり、文字が詰まったページが 15 ページを超える場合）、一連の小さなチュートリアルに分割することを検討します。
- 事前の準備: チュートリアルを中断なく進めるために設定が必要となる前提条件リソースやアクセス権を明記します。
バックグラウンドページ
- シーンを設定する: チュートリアルを書くときは、背景情報を与えると役立つことがよくあります。これは、プロダクトの概要を簡単に説明したり、UI の顕著な機能を要約したりすることを意味します。
基本的な例:
- Hello World: 提供する最初の例は、ユーザーがほとんど説明なくテストできるほど単純なものでなければなりません。Hello World のような例にする必要があります。チュートリアル全体のコンセプトを示すために、この例を作成の基礎として使用してください。
チュートリアルの内容
- フォーマットの使用の注意: テキストの書式設定（太字、イタリック体など）は読者の気を散らします。有効で必要な場合（警告、重要な学習事項を明記する場合など）にのみ使用してください。
- 一貫性のある文法: ユーザーの操作を記述するときには命令形を使用し、句点で文を終えてください。
- リンクの参照: 文脈で必要な場合は補足的なリンク（[リンクテキスト]（リンク URL））を付け、ユーザーが独自の調査を行えるようにします。
- スクリーンショット上のスポットライトを選択する: スポットライトは、UI 要素がどこにあるかを強調表示するアクションであり、ユーザーが画像を検索せずに要素を識別できるように位置を示します。
- ヒントの推奨: 適切な場合は、より直感的なソリューションとベストプラクティスをユーザーに提供するためのヒント（「**ヒント:**」で指定する）を追加します。
締め方
- 感謝の意を示す: チュートリアルを完了するために時間を割いたユーザーに感謝の意を示すトロフィーアイコン：🏆 を必ず追加する。
- 締めくくり: ユーザーにチュートリアルから学習して欲しい重要な知識を要約します。
- 次のステップ: 次のステップを提供することで、ユーザーの学習過程を支援します。こうしたステップは、おすすめのドキュメントや補足資料のほかに、別のチュートリアルである可能性があります。

チュートリアルのスタイルガイド | Cloud Shell | Google Cloud

https://cloud.google.com

Adobeのチュートリアルビルダーの記述ガイドライン

チュートリアルの構造

チュートリアルのタイトル
チュートリアルの内容を明確に伝えるようにタイトルを設定します。
- チュートリアルの説明
  そのチュートリアルの概要とメリットを説明するために使用します。
セクションのタイトル
タイトルは体言止めにし、そのセクション内の手順を実行することで得られる結果を簡潔に記します。
- セクションの説明
  必要に応じて、セクションの内容に関する状況説明や、その手順を実行する理由の説明に使用します。
- 手順