ユーザーの問題解決とプロダクトの成功を導くエンジニアのためのドキュメントライティング

『ユーザーの問題解決とプロダクトの成功を導くエンジニアのためのドキュメントライティング』（ジャレッド・バーティ他，日本能率協会マネジメントセンター，2023年3月30日）を読了した。

「知識の呪い」を乗り越える

1980 年代後半，「人間は他人が自分と同じ知識をもっていると思い込んでいる」ことをハーバード大学の経済学者グループが発見しました。彼らはこの認知バイアスを「知識の呪い」と名づけました。（位置 No. 466）

相手が自分と同じ知識をもっているとは限らないと認識を改めるべきである。そうすることで，話し方や資料づくりは相手にとって理解しやすくなる。

ユーザーの優先順位を明確にする

すべてのユーザーが同じわけではありません。ユーザー全員のニーズを満たすのは無理です。ビジネスやプロダクトにとって最も重要なユーザーを優先しましょう。（位置 No. 534）

プロダクトが何を目指しているかを理解し，それに共感するユーザーの声に耳を傾けるべきである。

ドキュメント計画の効能

良いドキュメントの計画は，次を可能にします。（位置 No. 1095）

• 情報に対するユーザーニーズを予想し，それを満たせるようになる
• 方向性に対してユーザーや社内のステークホルダーから早期のフィードバックが得られる
• ドキュメントだけでなく，サービスを含めた全体のユーザージャーニーにおけるギャップと不足箇所を明らかにする
• ドキュメント執筆・構成・公開について，他のステークホルダーと調整する

個人で製作するコンテンツにおいても，フィードバックを得る仕組みを整備しておくべきである。

コンテンツ運用の設計

• コンテンツをいつ公開するのか？
• 最終レビューと公開の責任者は誰か？
• コンテンツをどこで公開するか？
• コンテンツを公開するために，追加で必要となるソフトウェアツールは？
• 新しいコンテンツをどのように発表するか？（位置 No. 2382）

運用ルールを明確に定めることが重要である。

ユーザーアンケートの活用

1. Corg.ly のドキュメントにどの程度満足していますか？
2. 探していた情報を見つけられましたか？
3. 情報を見つけるまでどれぐらいかかりましたか？
4. その労力は，予想どおりでしたか？
5. ドキュメントを改善するために，何をしたらよいと思いますか？（位置 No. 2642）

定期的なフィードバック収集が，ドキュメント改善の礎となる。

課題の優先度管理

課題の優先度（位置 No. 2705）

• P0 : 緊急：すぐに解決する
• P1 : 次のリリースに必要
• P2 : 今後のリリースにあるとよい（ただし必須ではない）
• P3 : いつでもよい

優先度を明確にすることで，対応の効率化が図れる。

ドキュメントの機能品質

ドキュメントの機能品質は，次のカテゴリに分解できます。（位置 No. 2799）

• アクセシビリティがあること
• 目的があること
• 見つけやすいこと
• 正確であること
• 完全であること

これらを満たしているか定期的に確認することが望ましい。

コンテンツ導線の設計

「Every Page is Page One」の著者であるマーク・ベーカーは次のように書いています。（位置 No. 2845）

「見つけやすさの真の問題は，コンテンツの奥底にある間違った場所から，別の奥底にある正しい場所へ，読み手を連れていく方法にある」

読者を正しい情報へ導く導線設計が不可欠である。

構造品質の「3 つの C」

本書では，優れた文書にある「3 つの C」を使って，構造品質を定義します。（位置 No. 2891）

• Clear（明確な）
• Concise（簡潔な）
• Consistent（一貫している）

この 3 要素を意識して文書を作成すべきである。

トイルの自動化

「トイルとは，プロダクションサービスを動作させることに関係する作業で，手作業で繰り返し行われ，自動化することが可能であり，戦術的で長期的な価値を持たず，作業量がサービスの成長に比例するといった傾向をもつものです」（位置 No. 3422）

このような作業は自動化を検討し，コンテンツ更新の負担を軽減すべきである。

ドキュメントの鮮度管理

最終更新日に加えて，ドキュメントのコンテンツを確認する予定日を決めておくこともできます。たとえば Google では，鮮度状態を通知するために，社内ドキュメントの上部にメタデータを付与しています。ドキュメントが一定期間（たとえば 6 か月間）更新されていなければ，ドキュメントをレビューして，コンテンツが現在でも正確かどうか確認するように，ドキュメントオーナーにリマインダーが届きます。（位置 No. 3444）

最終更新日だけでなく，次回確認予定日も設定し，鮮度を保つ運用が望ましい。

ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング

ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング【電子書籍】[ ジャレッド・バーティ ]

エンジニアのためのドキュメントライティング [ ジャレッド・バーディ ]