「エンジニアのためのドキュメントライティング」 岩瀬 義昌

読み手の理解

「CHAPTER 1　読み手の理解」は、最も重要なポイントです。

ユーザーの理解を外すと、無価値なドキュメントが爆誕します。無価値なうえにメンテナンスコストがかかる最悪の状況が起こり続けるので、注意しましょう。ユーザーはドキュメントを読みたいのではなく、課題やニーズを解決したいのです。このことをまず頭に入れましょう。

ドキュメントを書く上で最も大事なこと

•  読み手となるユーザーを理解すること
• ユーザーは誰なのか？
• ユーザーは何を達成したいのか？
• ドキュメントで、どんな課題を解きたいのか？

どうすればユーザーを理解できるか

プロダクト開発をしているということは、必ず社内に議論の痕跡（図左）があるはずです。この痕跡を掘り起こすと、ユーザーが浮かび上がるので（仮説）次はその仮説を検証します（ユーザー理解の検証）。

1. 議論の痕跡を探す
2. ユーザーは誰か（という仮説）
3. ユーザー理解（の検証）

最も効率的なのは、ユーザーとの対話

ユーザー理解のためには、ユーザーと直接対話することがベストです。下記のような方法を用いて対話を試みましょう。

• 既存チャネルの活用
• サポートチケット
• インタビュー
• アンケート

とくに「ここが使いにくくて困った！」という “怒りの気持ち” で書いたサポートチケットは、ユーザーの生の声。ぜひ活用を。

対話したら知見をまとめよう

インタビューメモは情報量が多いので頭の中にインプットしておくことは、ほぼ不可能。ユーザーの声を検証しつつ、まとめる作業もお忘れなく。

• ユーザーペルソナ
• ユーザーストーリー
• ユーザージャーニーマップ

叩き台づくりにChatGPTを活用するのもアリ！

*ChatGPTを使用して作成したフリクションログの例

知識の呪い（認知バイアス）に、気を付けろ！

こんな経験はありませんか？

• 同僚が耳慣れない専門用語で話している
• 同僚が開発環境を作る手順を教えてくれない
• デバッグでエラーメッセージを教えてくれたが、他に必要な背景情報は伝えてくれない

恐らく同僚に悪気はなく、知っていると思っていて伝えていない可能性があります。これが知識の呪い（認知バイアスの1つ）です。

呪いを断ち切る2つの方法

王道の方法は「ユーザーへの共感」を徹底することです。次に効果的な方法は、フリクションログを作ることです。フリクションは直訳すると「摩擦」や「抵抗」を意味しますが、プロダクト開発においては、プロダクトを使う際に「うまく使えないな」と感じたことや違和感を指します。自らプロダクトを使ってみて、この違和感をログで残しておくことが大切です。　

*ChatGPTを使用して作成したフリクションログの例

ドラフトの執筆

ドキュメントを書くうえで最も難しいことは、ゼロから書き始めるところです。つまり効率的に作成を進めるためには白紙からの脱却がキーワードになります。

分からなくてもいいので、手を動かそう

手を進めるコツ

• 使い慣れたツールを使用する
• ドキュメント作成のために、新たに何かを学ぶ必要はない
• 紙・ペン・ホワイトボードなどなんでもOK

なんでもいいので、まず手を動かしましょう。書き始めてしまえばこっちのものです。

まずは、ユーザーと目的を整理する

• 冒頭で整理すること
  • 誰が・何のために・読みにくるのか？
  • 「どのタイプ」のドキュメントが適切か？

• 次にタイトルとアウトラインを決める
  • タイトル = ドキュメントを読んで達成できるゴールの要約
  • 例：カスタム会話型チャットボットの開発など

• アウトライン=ゴールに必要な大まかな要素や手順
  • 例：開発環境、 API認証の方法など

肉付けしていく

ユーザーの目的を整理したら次は中身を書いていきましょう。中身に使用する要素はこのあたりです。

• 見出し
  • ドキュメント内の道しるべ。ユーザーにとって、最も重要な情報を一番上に持ってくる
• 段落
  • ドキュメントの詳細を理解できる
  • 情報量が多く、読むのが大変
• リスト
  • さっと読みやすい
  • 重要度やアルファベット順にソートすると◯

• コールアウト
  • あまり馴染みがないかも知れないが結構重要
  • システムの注意喚起

ユーザーはちゃんと読まない

自分自身の行動を思い返してみてください。何かに困っているとはいえ、隅々までドキュメントを読むでしょうか。タイトルや見出しから何となく読んでいくはずです。これをFパターンといいます。

つまり、ユーザーが必要な情報をすばやく見つけられる構造にしておくことがベストなのです。（流し読みしやすい構成にする）

引用元：F-Shaped Pattern For Reading Web Content (original study)

最も重要な情報は冒頭で述べよ

もし手順書であれば、読了時点で達成できることを冒頭に書いておくと良いでしょう。

長い文章は分割し、読みやすくせよ

長文や長い段落は流し読みに向きません。見出し・リスト・サンプルコード・図表などを効果的に使用しましょう。

エンジニアは、まずサンプルコードを探す傾向が強い

エンジニア特有の事例ですが、動画や図よりも、まずサンプルコードを探す傾向が強いというデータがあります。サンプルコードについては本書 第5章で解説しているので、興味のある方はぜひご覧ください。

フィードバックの収集

ドキュメントはプロダクト機能の一部です。プロダクト同様にドキュメントそのものも仮説検証の対象になります。フィードバックを収集するフローは下記を参考にしてみてください。

• ユーザーがフィードバックを送信する経路を用意
• フィードバックを整理する
  • 有効なFBか？ 優先度をトリアージする

ドキュメントの品質測定

エンジニアにはお馴染みの言葉「計測できないものは改善できない」。ドキュメントの計測は、どのように実施すべきでしょうか。

優れたドキュメントとはなにか、答えられるか？

計測にあたってまずは良いドキュメントの定義を知りましょう。目的にかなっているドキュメントが、優れたドキュメントです。

目的

• ユーザーの特定の行動を促進する
• 組織のゴールを達成する

いいドキュメント
・見たいところに素早くたどり着ける
・図やチャートで理解を助けてくれる
#Forkwell_Library

— SONODA Takehiko (@OzoraKobo) March 17, 2023

優れたドキュメント、どちらが重要？

品質の計測は、機能品質・構造品質の2つに分けて考えることができます。さて、どちらの要素が重要でしょうか。

機能品質

• ドキュメントの目的やゴールが達成されているか？
• アクセシビリティがあること
• 目的があること
• 見つけやすいこと
• 正確なこと
• 完全であること

構造品質

• ドキュメント自体がうまく書かれているか？
• うまく構成されているか？
• 構造品質(C)
  • Clear (L)
  • Concise (¥)
  • Consistent (LTC13)

答えは、圧倒的に機能品質です。どれだけ美しく整理された構造であっても「目的」を果たさないドキュメントが優れているとはいえません。

計測できる要素は無限大、取捨選択を

Web計測ツールを使用すれば、PV・UU・直帰率など、あらゆるメトリクスの計測ができます。重要なのは何を計測するかではなく、なぜ計測するのかです。

• メトリクス活用の計画
  • なぜ計測したいのか
  • 計測した情報を何に活用するのか
  • その努力で、組織の目的・ゴールに近づけるのか

• 基準値を確立する
  • 計測（集める）だけでは意味がない
  • 基準値を決めてビフォーアフターを知ることが大切

日本語を学ぶ！おすすめの書籍

日本語特有のルールや人に伝わる文章術を学ぶなら、下記の書籍がおすすめです。

登壇資料はこちら