やったこと

• 書籍「エンジニアのためのドキュメントライティング」 PART1 (1章、2章) 読了

学んだこと

1章 読み手の理解

ドキュメントは、読み手のためのもの。
まずは、読み手のことを知る必要がある。

「知識の呪い」は、読み手の理解を妨げる。

❓知識の呪い
「自分が知っていることは、相手も知っている」と思い込むこと。

いくつかのステップを踏むことで、知識の呪いから逃れ、ユーザーを理解することができる。

• ユーザーのゴールを特定する
  • 「ドキュメントを読んで、ユーザーが達成したいこと」を突き止め、ゴールとして定める
  • 注意点として、プロダクトのゴールと、ユーザーのゴールは、必ずしも一致しない
• ユーザーを理解する
  • どんなユーザー（開発者・マネジャーといったロール、技術習熟度など）がドキュメントを読むのか、想定する
  • ユーザー全員のニーズを満たすことは不可能
    • ビジネスやプロダクトにとって最も重要なユーザーを優先すること
    • 例？）セキュリティ、SRE、開発では、いずれも求められる情報が異なるはず
• ユーザーのニーズを理解し、ドキュメントがそれをどう解決するか理解する
  • 詳細は後述
• わかったことを、ツール（ペルソナ、ストーリー、マップなど）を使ってまとめる
• フリクションログを使って仮説検証する
  • ユーザーの立場に立って、ユーザーの目的達成を阻害する要因（≒フリクション）を自分で体験する
  • よくあるユースケースを定義し、自分でなぞらえると良い

❓フリクション（ログ）
摩擦や抵抗のこと。
特に、ソフトウェアやサービスをうまく使えなかったことや違和感といった体験を示す。
"フリクションログ" だと、摩擦や抵抗を示す記録。

ユーザーのニーズを理解し、ドキュメントがそれをどう解決するか理解する

ドキュメントで答える必要がある（≒ユーザーが疑問に思う事項）のリストを作る。
よくある疑問は、以下の通り。

• これは何のプロダクト？
• 個のプロダクトが解決する問題は？
• どんな機能がある？
• 費用はどれぐらいかかる？
• どこから始められる？

出来上がったリストを、「アウトラインの作成」という形でまとめる。

アウトラインが出来上がり次第、「ユーザーは誰か」「ユーザーのゴール」「ユーザーのニーズ（アウトライン）」を検証する。
検証の際は、ユーザーのウォンツ（要望）ではなく、のニーズ（要求）に焦点を当てること。

主な検証方法は以下の通り。

• サポートチケットなど、存時の情報リソースを使う
• インタビュー、アンケートなどで、新しいデータを集める

2章 ドキュメントの計画

ユーザーのニーズに合わせて、コンテンツの種類（手順書、クイックスタートなど）を決定していく。

よく使われるコンテンツタイプは以下の通り。

• コードコメント
• README
• スタートガイド
• コンセプトドキュメント
• 手順書
  • チュートリアル
  • ハウツーガイド
• リファレンスガイド
  • トラブルシューティングドキュメント
  • 変更に関するドキュメント
  • リリースノート

質の高いドキュメントを作成するために、ドキュメント作成の計画を立てる。
以下の質問に答えることで、ユーザーにとって適切な情報を絞り込むことが出来る。

• 対象の読み手は誰か？
• プロダクトのローンチから、ユーザーに一番学んでもらいたいことは何か？
• 重要度順で考えると、どの機能からリリースされていくか？
• ユーザーはローンチに何を期待しているか？
• ユーザーがプロダクトや機能を使い始める前に必要な事前知識はあるか？
• 何のユースケースをサポートしているか？
• ユーザーが躓きそうな既知の課題や、フリクションはあるか？

これらの質問に答えることで、コンテキストを形成できる。
コンテキストが分かってくると、何から作り始めればよいか決められるようになる。

コンテンツのアウトライン作成から、ドキュメント計画を立てると良い。
以下、コンテンツアウトラインの例

タイトル	コンテンツのタイプ	簡単な説明
xxx スタートガイド	スタートガイド	xxxを使うための非常に簡単なデモと他のドキュメントへのリンク
xxx yyy機能の解説	コンセプト	yyy機能の仕組みの技術説明
認証方法	ハウツーガイド	認証スルタンのステップバイステップ手順
APIリファレンス	APIリファレンス	API呼び出し方法と構文の一覧
リリースノート	l変更履歴	xxxのリリースノート

以下、コンテンツタイプ別の追加情報。

• コードコメント
  • コーディング上の意思決定とその背景や、トレードオフを記録することで、読み手である将来の開発者の時間を節約する
  • 過剰なコメントは、保守コストが増大することを念頭に置くこと
• README
  • 以下の役割を担う
    • 読み手に、システム全体の概要を理解してもらう
    • リポジトリに対するチートシートとして機能する
    • ユーザーが利用する包括的なドキュメントの基礎（ポータル）として機能する
  • より詳細な情報が必要な場合は、重要なサブフォルダに追加情報を配置し、追加情報へのリンクをREADMEに貼る
  • テンプレート
• スタートガイド
  • 読み手（ユーザー）の立ち上げを支援する
  • より高度（≒専門的・詳細）なコンテンツへ進む前のスタート地点として機能する
  • スタートガイドを書く上で、自身に問うべき質問は以下の通り
    • サービス内容と核となる機能を一番短く説明するなら？
    • プロダクトをインストールして使うための最も簡単な方法は？
    • 新規ユーザーが感じる最も重要な疑問は？
    • サービスを使ってできるすごい事は何か？
• コンセプトドキュメント
  • サービスの裏側にある考え方とアイデアの理解を助ける
    • 手順書やチュートリアルの背景を説明する ... といった用途で作成する
  • 実装に関する詳細は、コンセプトドキュメントの領分ではない（手順書などの領分）
  • テンプレート
• 手順書
  • 具体的には、「チュートリアル」と「ハウツーガイド」が該当する
  • 読み手（開発者）が、特定のゴールを達成する方法を、手順として説明する
  • 以下、手順書作成時のガイド
    • できるだけガイド単体で読めるようにする
      • ユーザーが必要とするすべての行動を1つのページにまとめる
    • 手順数を最低限に絞る
      • ステップが多いほど、読み手は複雑に感じ、ミスが多発する
      • ステップが多いほど、手順書の保守が大変になる
    • 長文説明を避ける
      • 説明が長すぎると感じたら、コンセプトガイド等に分割すること
• チュートリアル
  • 手順書に分類されるドキュメント
  • 読み手に、特定のゴールを達成する方法（≒手順）を伝える（≒学習させる）ことを目的とする
  • 長く、時間のかかるチュートリアルを、ユーザーがやり遂げる可能性は低い
    • 長すぎる手順は、サービスが複雑すぎる可能性を示唆する
• ハウツーガイド
  • 手順書に分類されるドキュメント
  • 現実のビジネス課題を解決するための、特定の手順を説明する
    • チュートリアルのような学習目的ではなく、実装に基づく課題解決が目的
  • 以下、良いハウツーガイドの特徴
    • シンプルな言葉を使用する
    • 行動を明確にする
    • ハイツーガイドが解決する問題を継続的に改善する
  • ガイドの冒頭には、前提条件を入れると良い
• リファレンスガイド
  • 行動とその結果を説明する
  • APIリファレンス、用語集、トラブルシューティングドキュメントなどが該当する
• トラブルシューティングドキュメント
  • リファレンスガイドに分類されるドキュメント
  • 既知の問題に対して、その回避策、または解決策を説明する
  • 説明よりも、回避策に集中すること
    • 読み手の大部分は、「なぜ問題が発生したか」ではなく、「どうやったら問題を回避、または解決できるか」に関心を持つため
  • エラーメッセージとその説明、および解決策を列挙するのも手
  • テンプレート
• 変更に関するドキュメント
  • リファレンスガイドに分類されるドキュメント
  • 変更時期、顧客に影響が出たタイミングなどを整理し、トラブルシューティングに役立てる
  • 以下の情報を記録する
    • 過去のサポートバージョン、統合、または廃止予定の機能
    • パラメータや重要なフィールドの名前の変更
    • オブジェクトやリソースの移動
• リリースノート
  • リファレンスガイドに分類されるドキュメント（特に、変更に関するドキュメントの一種）
  • 変更履歴の背景情報を記載し、読み手に対して、ある変更が生じた理由を説明する
  • リリースノートには、以下の内容を記載する
    • 新機能
    • バグ修正
    • 既知のバグや制約
    • 移行方法
  • テンプレート