ドキュメントとは何か改めて考えました

本記事の目的

技術書籍を読みまして、学んだことと感想を忘れないように整理して残しておきます。

読んだ書籍

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

技術ドキュメントをリードした経験をもつエンジニア４名で書かれた本になります。

読もうと思ったきかっけ

思い返せば自分がドキュメントを書いた経験は、用途と目的が偏ったものでした。
システムの作り手に対して、システムがもつ思想や制約を自然言語で効率よく把握できるようにする目的でしか書いたことがなかったのです。
以下の点が学べそうでした。

• 非エンジニアであるユーザー向けの書き方
• 大規模なドキュメントを書く際のポイント
• ドキュメントの品質測定
• ドキュメントでフィードバックを収集してシステムを改善する方法

書籍の構成

PART1 ドキュメント作成の準備

CHAPTER1 読み手の理解

ターゲットとするユーザーをなるべく具体的に仮説立てする方法が書かれています。

CHAPTER2 ドキュメントの計画

ユーザー仮説に基づき用意すべきドキュメントの種類の決め方が書かれています。

PART2 ドキュメントの作成

CHAPTER3 ドキュメントのドラフト

ゼロからドキュメントを作成する困難への立ち向かい方が書かれています。

CHAPTER4 ドキュメントの編集

初版を改善し続ける方法が書かれています。

CHAPTER5 サンプルコードの組み込み

良い補足資料としてのコードサンプルの載せ方が書かれています。

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

画像や動画を用いることのメリットとデメリットが書かれています。

PART3 ドキュメントの公開と運用

CHAPTER7 ドキュメントの公開

公開する際に決めることが書かれています。

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

フィードバックを効率的に取り込む仕組みについて書かれています。

CHAPTER9 ドキュメントの品質測定

より良くするために客観的に品質を測定し改善することについて書かれています。

CHAPTER10 ドキュメントの構成

ドキュメントが増えても読み手を混乱させないための対処方法が書かれています。

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

自動化して保守すべき点や、乖離を排除して混乱を防ぐことについて書かれています。

学びと感想の記録

PART1 ドキュメント作成の準備

CHAPTER1 読み手の理解

知識の呪いと呼ばれる認知バイアスに気をつけるようにする。

知識の呪いとは、自分が知っていることは他人も知っていると思い込むこと。

具体的には、ユーザーが誰であって何を達成したいのかを、以下の取り組みにより理解するように努めることです。

• ユーザーのゴールを特定します。
  ビジネスの視点から、ユーザー全体に渡るゴールを定義します。ユーザーに知ってもらうことがゴールではないです。知って行動を変えてゴールにたどり着けるようにするのがゴールです。

• ユーザーのニーズを理解し、ドキュメントがそれをどう理解するかを理解します。
  ニーズをもつユーザーがもつであろう質問のリストを作ります。このリストにドキュメントは答えられる必要があります。
  例）これは何のプロダクトなのか？、プロダクトが解決する問題は何か？、費用はどのぐらいかかるのか？　などがあります。

• ユーザーを理解します。
  読み手を役割、経験、レベル、読んでいる状況でユーザーを定義します。
  次にユーザー間に共通する特徴を考ます。
  例）開発環境、OS、プログラミング言語などです。
  そこから仮説を立ててユーザーへのインタビューで検証します。
  （インタビューする相手の集め方、質問内容、質問する量などについても書かれております。）

ユーザーの言っていることを鵜呑みにして、ウォンツとニーズを履き違えないように注意します。

• 分かったことをペルソナ、ストーリー、マップにまとめます。
  得られたユーザーの理解の知見が失われないようにまとめます。

  • ペルソナ：ゴール・スキル・知識・状況の特徴で読み手を表現した半分架空のキャラクターでまとめます。
  • ストーリー：ユーザーが達成したい大まかなタスクやモチベーションを、以下のフォーマットで短くまとめます。
    「あるユーザーとしてあるゴールを達成するためにある活動をしたい」
  • マップ：ユーザーが特定のタスクの完了を試みる時に、プロダクトでたどる経路を図でまとめます。幸せを感じる箇所や改善可能な箇所を浮き彫りになります。
    作成手順は以下のようになります。
    • タスク定義
    • 利用チャンネルのリストアップ
    • チャンネルごとの操作手順
    • 各手順のユーザー体験のリストアップ
    • チャンネルと手順と体験をつなげて１つの流れにします

• フリクションログを使って仮説検証します。
  自分でソフトウェアを試して、ふるまいの期待と実際のギャップから、目的達成を邪魔するフリクションを洗い出します。場合によっては、プロダクトの修正点が見つかることもあります。

CHAPTER2 ドキュメントの計画

ユーザー調査の結果に基づいて、ユーザーニーズを解決するのに役立つコンテンツの種類を決定します。
ユースケースは役に立つので記載します。

コンテンツのタイプには以下があります。

• コードコメント：良いコードコメントは以下が守られています。

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

• README：以下の基本情報を含んでいます。簡潔、有益、正確、最新であることが大切です。

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

• スタートガイド
  第一印象と最初のユーザー体験を通じてユーザーを導くのがスタートガイドの重要な役割になります。
  単に触ってみたいだけの人もサポートできるように、以下を問いながら書きます。

  • サービス内容と核となる機能をいちばん短く説明するなら？
  • プロダクトをインストールしてつかうための最も簡単な方法は？
  • 新規ユーザーが感じる最も重要な疑問は？
  • サービスを使ってできるすごいことはなにか？

• コンセプトドキュメント
  サービスの裏側にある考え方とアイデアの理解に役に立つ情報を書きます。
  主張は入っても良いですが、実装に関する詳細に立ち入らないようにするべきです。

• 手順書
  チュートリアルとハウツーガイドを含みます。１つの手順につき、ユーザーが取る１つの行動を説明するようにします。
  すばやく効率的にやりたいことができるように書く基本的なポイントは以下です。

  • 必要とする情報を１ページにまとめる。
  • 必要とする手順数はなるべく絞る。長い手順や情報量が多いとユーザーのミスを誘発する。
  • サンプルコード以外は簡潔さを心がける。付加的なコンテンツも載せすぎるとユーザーを怯ませてしまう。

• チュートリアル
  学習に焦点をあてて、特定のゴールを達成する方法をユーザーに伝える手順です。
  手順数が10を超える場合は、対応するユースケースが複雑すぎる可能性があります。
  もしかしたらサービス自体が複雑で見直す必要があるかもしれません。

• ハウツーガイド
  実際のコード実装がどうなるのかに焦点をあてて、特定の手順を実行することで現実の課題をどのように解決できるかを説明するものです。
  サービスの限界に位置するようなエッジケースはユーザーを迷子にさせるので書かないようにします。

• シンプルな言葉を選ぶ。

• 行動を明確にする。

• 解決しようとする問題を継続的に改善する。

• リファレンスドキュメント
  行動とその結果を扱います。以下の内容を含みます。

  • APIリファレンス。以下の点をおさえると良い。
    • すべてのリソースとエンドポイントに対する詳細なリファレンスが提供されている。
    • 豊富な例が提供されている。
    • ステータスコードとエラーメッセージが定義され、リストアップされている。
    • ユーザーは開発が始まるとAPIリファレンスを参照することが多くなるので、他のドキュメントとは別れている。
  • 用語集
    ドキュメント内での用語の一貫した活用を推進し、読み手を苛立たせることを防いだり、理解を助けたり、ユーザーの信頼性を損なうことを防いだりします。包括する必要はないですが、ユーザーがサービスを使うに当たって必要な用語は定義しておきます。
  • トラブルシューティング
    開発側が想定していないエッジケース（想定外のユーザー行動、非推奨の動作）を含む既知の問題の回避策を示し、タスクの完了という目的を果たせるようにします。発生理由を過度に説明するのは避け、回避策に集中できるように書くと良いです。この情報を参照するユーザーは苛立っているので、できる限り早く問題が解決するように書きます。またエラーメッセージをリストアップして書く場合は１ページにまとめておくと、効率的に検索できるようになります。

• 変更履歴
  サポートやエンジニアの内部チームにとって有用な記録になる。次のデータを含む変更を時系列でリストアップします。

  • 過去のサポートバージョン、統合、または廃止予定の機能
  • パラメータや重要なフィールドの名前の変更
  • オブジェクトやリソースの移動

• リリースノート
  変更に対する背景情報が得られるように以下のように書きます。
  「ここが変更箇所です。理由はこうです。前はこうでした。これからこうなります。」
  以下の内容を記載対象とします。

  • 新機能
  • バグ修正
  • 既知のバグや制約
  • 移行方法

良いドキュメントの計画は次のことを可能にします。

• 情報に対して予想されるユーザーニーズを満たせるようにします。
• 方向性に対してユーザーや社内のステークホルダーから早期のフィードバックが得られるようになる。
• ユーザージャーニーおけるギャップと不足箇所が明らかになる。
• 執筆、構成、公開について他のステークホルダーと調整が可能になる。
• 書くべき内容のアウトラインが定まり、執筆に集中できるようになる。

PART2 ドキュメントの作成

CHAPTER3 ドキュメントのドラフト

他の人が理解できるように、考えを明確で簡潔な言葉にすることの難しさを認めることが大切です。
読み手、目的、コンテンツパターンを箇条書きで書き出すところから取り掛かります。
そこからユーザーから見た目的を言い換えた簡潔なフレーズをタイトルとします。

まずは順番は気にせず、コンセプトを作り上げるのに必要な全ての手順を書き出します。
次に以下に注目してアウトラインを完成させます。

• 事前情報や設定情報を追加すべきかどうか？
• 飛ばしている手順があったり、不完全な説明になっていないか？
• 手順は合理的な順で並んでいるか？

ここまできたらアウトラインに情報を肉付けする形でドラフトを書いていきます。肉付けする情報には以下が使えます。

• 見出し：道しるべとなるよう、簡潔・明確・具体的に書く。
• パラフラグ：文の数が５個以下になるように目指して書く。大きな段落は読み飛ばされるので分割する。
• 手順：番号付きリストを使うと良い。最後に正常に完了したかを確認する方法を記載する。
• リスト：関連情報を読みやすい形にまとめられる。良く使われるものから順に書く。
• コールアウト：警告や注意やヒントを色・アイコンを使って強調して書く。

研究によると、人は「F」型に流し読むパターンが多いそうです。つまりタイトルとサブタイトルを横２列の向きで読んで、ページの下に向かって読む。よって重要なことは冒頭で述べるのが良いそうです。

書くのに行き詰まったら以下の戦略が役に立ちます。

• 完璧主義からの脱却する。
• 助けを求める。
• 足りないコンテンツはTODOコメントで残して後で書く。
• 最初は順不同で書く。
• メディアを変える。テキストエディタを変える、アナログ的にホワイトボードに描いてみる。

CHAPTER4 ドキュメントの編集

編集とはドキュメントを、文法・読みやすさ・明確性・効率的かのポイントで改善するプロセスです。
このプロセスを作成と分けてステップバイステップにすることで、効率的に作成を行えかつ客観的かつ批判的な視点で見直すことができます。
次の視点で編集を周回させて行います。

• 技術的な正確さ
• 完全性
• 構成
• 明確さと簡潔さ

編集プロセスを確率して他の人と手分けできる仕組みを作ることにより以下のメリットが得られます。

• より客観的な視点を通じたフィードバックが得られ品質が一定する。
• 負荷を分散して継続することができる

フィードバックする側も以下を心がけて良いフィードバックを心がける。

• 人ではなくアイデアに集中する。
• 建設的な提案を続ける。
• フィードバックに反応するための時間を確保する。

批判は建設的な追加提案とともになされるべきである。
間違っているという言い方はせず、～したら良くなるという言い方を心がける。

CHAPTER5 サンプルコードの組み込み

どうやっても自然言語よりコードで説明したほうが伝わりやすいことがあります。以下の点に気をつけるとより理解されやすくなります。

• 説明文とサンプルコードはそばにあること。
• 過不足のない量で説明されていること。
• 言語習慣に従ってサンプルコードが書かれていること。
• 信頼できること。つまりそのままで動作しかつ、余計なことをしない。
• 拡張可能であること。つまり、読み手自身のデータを入力スべき箇所が明確である。

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

文章から全体的な意味を理解する脳の処理は非効率だそうです。
**「一枚の絵は1000の言葉ほどに雄弁だ」**という言葉が示す通り、人の脳は画像の方が素早く処理することができ、かつ記憶の定着が良いそうです。
しかし、ビジュアルコンテンツはあくまで理解を促進する補助である。次の点をおさえないと情報の伝達を妨げることになるので注意します。

• 理解容易性：矢印が交差していたり、ラベル不足だったり、抽象化のレイヤーが異なると読み手が混乱する。
• アクセシビリティ；代替テキストを用意する。
• パフォーマンス：高速なインターネットを誰もが使えるわけではないことを考慮する。

代表的な図の種類

• ボックスと矢印
• フローチャート
• スイムレーン

複雑すぎる図は文章よりも理解しにくくなるため、１つの図は１つのコンセプトを表したものにします。
読み始める箇所をわかりやすくし、ラベルで補足するとさらに読みやすくなる。ただし小さな文字は避けます。
色に一貫性をもたせるようにします。

映像コンテンツは作成が難しく保守コストも高い。用意する場合は専門家にお願いしたほうが良いとのことです。

PART3 ドキュメントの公開と運用

CHAPTER7 ドキュメントの公開

リリース時に完璧なドキュメントはほとんどありません。公開への不安に対処する最も良い方法は、まず公開してからフィードバックに基づいて更新を繰り返えします。
有害なドキュメントでないことを確認し、公開しても良いかの判断を行う最終決定者を置きます。（完璧かどうかで判断はしません。）
コンテンツの届け方を決めます。ユーザーがいる場所に公開して、ユーザーが出会えるようにします。

• 社内チームがユーザーなら社内Wikiやイントラネットで公開する。
• ソースコードを使う社外の人がユーザーであれば、ソースコードのリポジトリに置く。
• インストールしたいエンドユーザー向けなら、インストールする前から参照できるように、ソフトウェアの外部に置く。

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

ユーザーからのフィードバック収集や適応を効率的に行うための仕組みを構築します。

• フィードバックチャンネルを確立する。
  • ドキュメントページから直接受け取れるようにする。
  • サポートチームのチケットをモニタリングする。
  • ドキュメントに対して、役にたったかどうかの反応を集める。
  • メール等でユーザーサーベイを行う。
  • 顧客に定期的に連絡する。
  • ユーザー会を設立し、アーリーアダプターとの接点を持つ。

得られたフィードバックに対して、次の理由から優先度と対応可能性からトリアージを行います。

• 課題に早く反応するため。
• 依頼された仕事が際限なく残り続けるのを防ぐため。
• 課題に対する優先度の統一基準を作るため。
• 最も重要で効果のあることに限られたリソースを振り向けるため。

CHAPTER9 ドキュメントの品質測定

ドキュメントの品質とは目的にかなっているドキュメントであればあるほど品質が高いと言えます。

• 機能品質：目的やゴールが達成できる内容となっているかで判断します。
  • アクセシビリティがあること。
  • 目的があること。
  • 見つけやすいこと。
  • 正確であること。
  • 完全であること。
• 構造品質：読みやすい、混乱しない構成で書かれているかで判断します。
  • 明確である。
  • 簡潔である。
  • 一貫している。

機能品質は構造品質よりも優先されます。内容が良くなければ、書き方を工夫しても読み手には嬉しくないからです。

Web解析ツールから得られる品質測定メトリクスは以下があります。

• ユニーク訪問者数
• PV数
• ページ滞在時間
• 直帰率
• 検索キーワード分析
• リンクの検証
• TTHW：サービスを使い始めてから、シンプルなタスクを完了させるまでにかかった時間。

CHAPTER10 ドキュメントの構成

ドキュメントが増えてきた時に読み手に道しるべを示し、ユーザーがサイトをより高速に、かつより直感的に巡回できるようにします。読み手が頭の中にコンテンツ構成の地図であるメンタルモデルを作りやすそうかどうかで判断します。

• サイトナビゲーションと構成
  • 将来追加されるコンテンツの予定図も含めた地図です。階層構造は以下の３つがあります。
    • シーケンス
    • 階層
    • Web
• ランディングページ
• ナビゲーションの手がかり
  • 適切な情報とどれぐらい近くにいるかをユーザーが分かるようにします。
    • パンくずリスト
    • サイドナビゲーション
    • ドキュメントに関連情報とメタデータ
    • 前提条件、次のステップ、追加のセクション
    • 間違ったページの代わりにおすすめを示す脱出口

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

プロダクトとドキュメントの内容のギャップが広がるとユーザーからの信頼は失われてしまいます。これを防ぐために、以下のポイントをおさえて保守を継続することが大切です。

• 保守の計画
  • 保守しやすいようにコードと合わせてドキュメントの更新計画も一緒に行う。ユーザーへの影響分析を通してドキュメントを更新または追加する必要があるかを探る。
  • ドキュメントオーナーを決めることで責務を明確にする。
  • ドキュメントに時間をかけることにペナルティを課してはいけない。
• 保守を自動化する
  • サービスの成長と比例して作業量が増え、かつ人手でやることに価値がなく、自動化できるタスクをトイルという。以下のようなトイル作業は自動化する。
    • コンテンツの鮮度確認：最終更新日から半年経過したらリマインダー通知する。
    • リンクチェッカー：CI/CD時や公開後にクローリングでチェックする。
    • リンター：誤字、攻撃的や排他的な言葉のチェックを行う。
    • リファレンスドキュメントの自動生成
• 不要になったドキュメントの削除
  • 非推奨化のアナウンスを行う。機能が削除された時点でドキュメントとこのページに対するリンクを削除する。

まとめ

• ドキュメントは、コードを読むリテラシーがない人にわかってもらうために、わざわざ手間をかけて自然言語で置き換えたものにすぎないというイメージを、この業界でお仕事を初めてからしばらくは感じていました。
• 文章を書くのが苦手だったこともあり、ただただ億劫でした。
• お仕事を続ける中で、本や同僚が書いた文章の美しさと、それがもたらす効果を見てきて、自然言語で伝えることの大切さが少しずつわかってきた気がします。
• どんなに良いプロダクトも使ってもらえてなんぼです。飲み込みやすいドキュメントとセットになっていることは、競合との差別化要因になると思います。
• 最近は動画でのマニュアルも増えてきましたが、保守性やコストを考えると、文章によるドキュメントはベースとして引き続き需要があり続けると思います。
• 本書を読んでドキュメントに戦略的に取り組む方法を学ばせてもらいました。
• ここでは紹介しているのは本書で書かれている内容のごく一部です。興味を持たれた方は是非お手にとって読むことをおすすめします。

最後までお読みくださりありがとうございました。