「エンジニアのためのドキュメントライティング」を読みました

はじめに

「エンジニアのためのドキュメントライティング」（以下本書）は、日本能率協会マネジメントセンターから出版されている書籍です。

ジャレッド・バーティ (著), ザッカリー・サラ・コ―ライセン (著), ジェン・ランボーン (著), デービッド・ヌーニェス (著), ハイディ・ウォーターハウス (著), 岩瀬 義昌 (翻訳)

https://www.amazon.co.jp/dp/4800590833

翻訳者の方は、Podcast「fukabori.fm」で有名な岩瀬氏です！

今回は、本書の内容を軽くまとめつつ、読後の感想などをお伝えしていきます。

CHAPTER 1 読み手の理解

ドキュメントを書くためには、そのドキュメントのユーザー（読み手）への共感が必要。

ユーザーのゴールを特定する

ユーザーがドキュメントを読んで達成したいことをまず理解する。

なぜドキュメントを書く必要があるかというと、ユーザーになんらかのタスクを完了してもらいたい、または行動を変えてもらいたいから。

ビジネスの視点から、ユーザーのゴールを定義することが大事。

ユーザーを理解する

ユーザーは、プロダクトに詳しくないという前提に立つ。

以下の項目について意識する。

• ユーザーペルソナ
  • 名前、開発スキル、言語、開発環境、役割などを定義する
• ユーザーストーリー
  • そのユーザーが何を実現したいか
• ユーザージャーニーマップ
  • どんなユーザーが、どんなシナリオで、どんな体験をするか、を表現する

CHAPTER 2 ドキュメントの計画

ドキュメントのコンテンツ（内容）には、以下のタイプがある。

コードコメント

良いコードコメントは以下の特長を持つ。

• 簡潔に保たれていること
• 関連性があること
• 過剰にならない程度に自由に使われていること

README

READMEは以下の基本情報を含んでいる。

• 概要(コードが実行していること)
• インストール方法
• トラブルシューティング手順
• コードのメンテナー
• ライセンス情報
• 更新履歴
• 基本的な例
• より詳細な情報やドキュメントへのリンク

スタートガイド

ユーザー側のコードにそのプロダクトを埋め込むための手順や、サンプルコードなど。

詳細な手順やハウツーは記載せず、簡潔に保つ。

コンセプトドキュメント

サービスの考え方やアイデアの理解を助けるもの。

概要やコンセプトなど。

手順書

チュートリアル、ハウツーガイドなど。

以下の点に注意する。

• ガイド単体で読めるようにすること
• 必要な手順数は、ユーザーが必要とするものに絞ること
  • たくさんのステップはユーザーにとって複雑になってしまう
• 長い説明を避けること
  • 数行の説明文、適切な画像の配置が有効

リファレンスドキュメント

リファレンスの例として、良いAPIドキュメントの特長を挙げる。

• 全てのリソースとエンドポイントに対する詳細なリファレンス
• 豊富な例
• ステータスコードとエラーメッセージが定義され、リストアップされている

他に、用語集やトラブルシューティングなどがある。

ドキュメントを計画する

ユーザーにとって適切な情報に集中するため、以下の問いに答えていくとよい。

• 対象の読み手は誰か？
• ユーザーに学んでほしいことは何か？
• どの機能からリリースされていくか？
• ユーザーはローンチに何を期待しているか？
• ユーザーがプロダクトや機能を使い始める前に必要な事前知識はあるか？
• なんのユースケースをサポートしているか？
• ユーザーがつまづきそうな基地の課題やフリクションはあるか？

これらの情報をまとめ、以下のようにアウトラインを作成する。

• タイトル
• コンテンツのタイプ
• 簡単な説明

CHAPTER 3 ドキュメントのドラフト

ドキュメントのタイトルは、「ドキュメントを読むことで達成できるゴールを要約したもの」にすること。

ゴールが複数ある場合は、ドキュメントを分ける必要がある。

まずは見出しのみのアウトラインを作る。

見出しに対して肉付けしていく。

ドキュメントの読み手には、2つの基本的かつ矛盾する真実がある。

• 読み手は情報を探してドキュメントにたどり着く
• 読み手は書いてある情報をほとんど読まない

コンテンツが流し読みしやすくなるように記述すること。

具体的には、以下の点を意識する。

• 最も重要な情報を冒頭で述べる
• 大きな文章のかたまりを分割する
• 簡潔さと明確さに向けて努力する
• 完璧主義からの脱却（完璧である必要はない）
• 助けを求める（誰かにレビューしてもらう）
• 足りないコンテンツを強調する（TODOコメントを残す）
• メディアを変える（書けなくなったら、エディタやプログラムを変えてみる）

ここまででできたドキュメントについて、以下の問いに答えてみる。

• 大見出しはドキュメントのゴールを要約しているか？
• 複数の見出しによってドキュメントは要約されているか？
• 読み手のニーズに応えているか？
• 情報の流れは読み手にとって理解しやすいか？
• フリクションログの課題は解決されているか？
• なんらかのドキュメントパターンかテンプレートに従っているか？
• 全手順が動作することを確かめたか？

CHAPTER 4 ドキュメントの編集

ドキュメントについては、以下の観点で編集していくとよい。

• 技術的な正確さ
  • 手順は正確か？
  • 用語は正確か？
  • 関数、パラメータ、エンドポイントの命名や説明は正確か？
• 完全性
  • TODOが残っていないか？
• 構成
  • タイトルと見出しから、何についてのドキュメントなのかがわかるか？
  • ドキュメントに一貫性はあるか？
  • 他のドキュメントに置くべきセクションはないか？
  • テンプレートがある場合、テンプレートに沿っているか？
• 明確さと簡潔さ
  • 不要な記述はあるか？
  • 読み手が戸惑うような熟語やスラングはあるか？
  • 避けるべき偏った言葉は使われていないか？

ドキュメントはまず自分自身でレビューする。

その後、同僚などにレビューを依頼すること。

CHAPTER 5 サンプルコードの組み込み

良いサンプルコードは、コードに対する説明以上に多くを語る。

開発者は、文章を読み飛ばす一方で、サンプルコードを探している。

サンプルコードには以下の2種類がある。

実行可能なサンプルコード

APIのリクエストコマンドなど。

開発者がコピーアンドペーストするだけで実行できるコード。

サンプルのAPIリクエスト
$ curl 'https://document-writing.com/api/v1' -i

説明のためのコード

APIのレスポンスなど。

サンプルのAPIレスポンス
{
    "id": 1,
    "name": "woof"
}

以下の点が重要。

• 説明されていること
• 簡潔であること
• 明確であること

CHAPTER 6 ビジュアルコンテンツの追加

画像は、文章と比べて少ない認知処理で複数の事柄を関連づけることを助けてくれ、文章よりもはるかに素早く理解を深められる。

ビジュアルコンテンツはとても有用だが、あくまで補助であると理解すること。

具体的には、以下のコンテンツが役に立つ。

スクリーンショット

UIを見てもらいたい場合に有効。

以下の点に注意する。

• 文章中からの参照もしくは説明と一緒に表示されること
• 説明や関連する文章の近くで表示されること
• UI以外をスクリーンショットに含めないこと
• UIの関連情報を全て含まれていること
• 大きすぎず、小さすぎないこと

画像の一部に矢印やブロックをつけるのも有効。

図には以下の種類がある。

• ボックスと矢印
  • 情報の流れを明示できる
• フローチャート
  • プロセスを明示できる
• スイムレーン
  • 複数のアクターがいる場合などのプロセスを明示できる

映像コンテンツは効果的だが、更新の手間がかかるため、古くなってしまう恐れがある。

CHAPTER 7 ドキュメントの公開

コンテンツのリリースをするために、以下の問いに答えていく必要がある。

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

プロダクトのリリースと整合性をとり続けるために、リリースプロセスを作ること。

CHAPTER 8 フィードバックの収集と組み込み

ドキュメント公開後は、ユーザーの声に耳を傾けること。

以下のように、フィードバックチャンネルを作るとよい。

• ドキュメントページから直接フィードバックを受け取る
• ドキュメントに対する感情を集める
• ユーザーサーベイを実施する

そうして集めたフィードバックを、以下の基準でトリアージする。

• 課題は有効か？
• 課題は修正可能か？
• 課題はどれくらい重要か？

CHAPTER 9 ドキュメントの品質測定

ドキュメントの品質は、大きく以下のカテゴリに分けられる。

• 機能品質
  • ドキュメントの目的やゴールが達成されているか
• 構造品質
  • ドキュメント自体がうまく書けているか。うまく構成されているか

機能品質

以下の点に注目する。

• アクセシビリティがあること
  • 読み手の言語で書くこと
  • 読解レベルは、小学校高学年を基準にする
• 目的があること
  • ゴールを達成しているか
• 見つけやすいこと
  • 見つけやすい場所にドキュメントを配置する
• 正確であること
  • 正確で最新の情報を載せる
• 完全であること
  • ユーザーが成功するために必要な情報が全て載っていること

構造品質

「3つのC」を意識する。

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

機能品質の方が、構造品質よりも重要である。

なぜなら、どれだけうまく書かれていても、ゴールを達成していなければ不十分だからだ。

ドキュメントの品質のため、以下のメトリクスが有効である。

• ユニーク訪問者数
• PV数
• ページ滞在時間
• 直帰率
• 検索キーワード分析
• 読解レベルもしくはテキストの複雑性分析
• ドキュメントに関係するサポートチケット
• リンクの検証
• TTHW（Time to Hello World）

CHAPTER 10 ドキュメントの構成

ユーザーがドキュメントをより高速に巡回できるよう、以下の要素を加えるとよい。

• サイトナビゲーションと構成
  • 関連ページをまとめ、構造化する
• ランディングページ
  • 読む量を最小限に、適切なコンテンツへとユーザーを誘導するページ
  • 短く、目を通しやすく、専門用語を使わずに、読み手に有益な情報を載せること
• ナビゲーションの手がかり
  • パンくずリスト
  • サイドナビゲーション
  • ラベルとメタデータ
  • 前提条件、次のステップ、追加の情報セクション
  • 読み手が間違ったページにやってきた場合に、代わりのページをおすすめする脱出口

以下の問いを自分に投げかける。

• このページは役立っているか？
• このページは最新化されているか？
• このページは適切な位置に配置されているか？

必要に応じて、以下のアクションを実行する。

• 削除する
• 正確性をレビューする
• 他のドキュメントと統合する
• 複数のドキュメントに分割する

CHAPTER 11 ドキュメントの保守と非推奨化

アプリケーションは時間と共に成長し、進化する。

ドキュメントは日々更新されなければならない。

保守の計画

ドキュメントを保守するには、コードとドキュメントの整合が必要になる。

新機能を設計するときは、コードとコンテンツの両方に必要な更新内容を検討する。

具体的には、以下の問いに答えていく。

• 今回の変更によって、ユーザーにどのような影響があるか？
• 今回の変更によって、既存機能にどのような影響があるか？
• 既存のドキュメントには、どのような影響があるか？
• ユーザーを支援するために、ドキュメントを新規に作る必要があるか？

リリースとドキュメントの整合をとるには、ドキュメントにチケットのリンクなどを添付する方法がある。

ドキュメントオーナーを決めたり、保守作業に報酬を支払うことも有効だ。

以下のツールを使用することも有効である。

• ドキュメント自動作成ツール
• リンクチェッカー
• リンター

ドキュメントからコンテンツを削除する

誤った情報を伝えないために、コンテンツを非推奨化すること。

非推奨の機能を使用するユーザーが完全に移行したと判断できた時に、ドキュメントを削除する。

内容のまとめは以上です。

感想

ドキュメントのユーザー（読み手）を意識する、という視点はこれまで意識したことがなかったので、大変勉強になりました。

「ドキュメントの目的・ゴール」という概念の重要性も知ることができました。

そもそもドキュメントはなぜ必要かというと、ユーザーの成功のためである！ということをキッパリと言語化してくれて、腹落ちしました。

普段何気なく読んでいた、LaravelやDockerのドキュメントを見直すと、本書に書かれているプラクティスに沿って書かれていることに気づかされます。

自分の業務についても、チームメンバーに対して「ドキュメントを書きましょう！なぜなら〜」と主張できるようになろうと思います。

忘れた頃にまた読み返したい、素晴らしい書籍だと感じました。