やったこと

• 書籍「エンジニアのためのドキュメントライティング」 PART3 (7,8,9,10,11章) 読了

学んだこと

7章 ドキュメントの公開

最初から完璧を求めない。
リリース後、フィードバックに基づいて更新を繰り返すつもりでいること。

ドキュメントの公開に当たって、やるべきこと

• コンテンツリリースプロセスの構築
• 公開タイムラインの作成
• 公開の最終決定と承認
• 読み手へのコンテンツの告知

コンテンツリリースプロセスの構築

リリースするまでの計画（≒流れ）を予め用意しておく。
以下の質問に答えることで、計画に必要な情報を収集できる。

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

公開タイムラインの作成

ドキュメント公開に向けて必要なタスクについて、作業計画（=> 公開タイムライン）を作成する。

◆公開タイムライン
公開に向けて必要不可欠なタスクがすべて揃っていること、
および、タスクの完了に向けて十分な時間があることを確認するための方法の一つ

イメージはガントチャート。

基本的には、ドキュメントは、対応するアプリケーションと同時に公開する。
そのため、公開タイムラインのタスクには、ソフトウェアのリリース作業情報も含めると良い。

公開の最終決定と承認

ドキュメントのリリース・差し止めを判断する最高責任者を 一人任命する。
その人物にリリース・差し止めを判定してもらう。
差し止めの主な基準は、「ドキュメントがユーザーにとって有害かどうか」

コードレビューと同じタイミングでドキュメントのレビューを挟む。
こうすると、リリースする機能に関するドキュメントもレビュー済みであることを確信できる。

読み手へのコンテンツの告知

ドキュメントを公開しても、ユーザーに読まれなければ意味がない。
ユーザーに合わせて、適した公開方法を選択すること。
そして、読み手の取って最も合理的なスタート地点に、リリースしたドキュメントのリンクを貼ること。

• 社内向けだと、社内でよく使用されるWikiなど
• ソースコードやエンドポイントを使用する外部の開発者であれば、リポジトリの中に含めるとよさそう
• サービス利用者であれば、少なくともソフトウェアの外部にドキュメントを配置すること

◇◆◇◆◇

コンテンツのリリースに慣れてきたら、改善できそうな箇所が無いか探してみること。
公開プロセスの自動化も、良い選択肢。
ただし、最初は作りこみ過ぎず、最も単純な個所から取り組むと良い。

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

リリースしたドキュメントを改善するために、ユーザーからフィードバックを受け取る。

• フィードバックチャンネルの作成
• フィードバックからアクションを決定
• フィードバックのトリアージ

フィードバックチャンネルの作成

ユーザー数、ユーザーの属性に応じて、フィードバックチャンネルを設ける。

• ドキュメントページからフィードバックを直接受け取る
• サポートチケットをモニタリングする
• ドキュメントに対する感情を測定する
  • 「このページは役立ちましたか？」「「はい」、「いいえ」」のアンケート
  • 感情は、コンテキストの影響を受けやすい
    • トラブルシューティングページは、低評価をつけやすい傾向にある ... など
• ユーザーサーベイを作成する
• ユーザー会を設立する

ユーザーの目的は、ドキュメントを読んで目的を達成すること。
フィードバックを送信する事ではない。
ユーザーの労力が少なくすることを念頭に、色々なチャンネルを検討すること。

フィードバックからアクションを決定

フィードバック情報を基に、ユーザーの目的達成を妨げる障害を排除する（または、目的達成を更に助ける）アクションを決定する。

フィードバックのトリアージ

フィードバックのアクションに対して、優先順位をつけて対応する。
優先順位をつける際、以下の評価項目を考えると良い。

• そもそもドキュメントに関連する課題であるか？
  • ドキュメントに関係ない課題であれば、関連部署にエスカレーションする
• ドキュメントの改善に向けて、アクションに落とし込めるか？
  • 再現可能？
  • 「全部書き直してほしい」とか「役に立たない」のように、曖昧で範囲が広すぎると、アクションに落とし込めない
• 課題はどれぐらい重要か？

アクションを実行し、課題に対応したら、フィードバックを送ってくれたユーザーに感謝を伝えると良い。

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

目的にかなっているドキュメントこそ、優れたドキュメント。

ドキュメントの目的は、以下の二点。

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

上記二点に合わせて、ドキュメントの品質を次の二つの基本的なカテゴリに分類できる。

• 機能品質 : ドキュメントの目的やゴールが達成されているかどうか
• 構造品質 : ドキュメントが上手く構成されているか、読みやすいか

機能品質

ドキュメントが、役割（≒ユーザーが目的を達成すること）をどの程度果たしているかを表す指標。

機能品質は、以下のカテゴリに分解できる。

• アクセシビリティがあること
  • 難しい文法、語彙を使用しない
  • ユニバーサルデザインを導入している
• 目的があること
  • 目的に加え、想定読者や読み手が達成できることを書いておくと良い
• みつけやすいこと
  • 以下を表す指標
    • どれぐらい簡単に読み手がコンテンツにたどり着けるか
    • どれぐらい簡単にコンテンツ内を読み進めることが出来るか
  • サイト全体における現在地を表示するなど、各ドキュメントに、できるだけ多くのコンテキストを記載すると良い
• 正確であること
• 完全であること
  • 以下を満たすこと
    • 読み手が従うべき前提条件がすべて一覧化されている
    • タスク完了に必要なすべてのタスクが載っている
    • 読み手が取るべき次のステップが定義されている

構造品質

ドキュメントをいかに簡単に理解できるかを表す指標。

以下3つのCで定義する。

• Clear （明確な）
  • ドキュメントをいかに簡単に理解できるか
  • 難解な専門用語や、不必要に長い言葉を避ける...など
• Concise （簡潔な）
  • 読み手に関連する情報とゴールに関する情報のみが含まれること
  • 短くてわかりやすいこと
  • =>不要な言葉や不必要なコンセプトは記載しないこと
• Consistent （一貫している）
  • コンテンツの構造、導入するコンセプト、言葉の選択（≒語彙）がドキュメント全体で同一であること

機能品質と構造品質の優先順位

機能品質の方が重要。
=> どれだけうまく構成されていても、読み手が目的を達成できなければ、ドキュメントの存在意義はない。

レビューやメトリクス収集の際も、「機能品質を満たしているか」が重要な観点になる。

なお、レビューやメトリクス収集の際、人間は構造品質に目が行きやすい。
注意すること。

メトリクスを収集して品質向上に役立てる

「目的にかなっているドキュメントこそ、優れたドキュメント」であることを念頭に、収集するメトリクスを決定する。
知りたいこと（質問）に合わせて、収集するメトリクスを決定する。

質問	ドキュメントのメトリクス
ドキュメントを読んでいるユーザー数は？	ユニーク訪問者数
最も閲覧されているドキュメントは？	PV数

など

収集したメトリクスを評価する場合、以下の点を念頭に置くこと。

• 計画を作る
  • なぜ測定したいのか？
  • その情報を使って何をするのか？
  • その努力で、どのように組織のゴールを前に進めることが出来るのか？
• 基準値を確立する
  • 比較できるようにする（比較できなければ、評価できない）
• コンテキストを検討する
  • ドキュメントのコンテキスト次第で、メトリクスの解釈を誤る可能性がある
  • 例） PV数増加 => 利用者急増？ => 実はエラーページのPV数が大きく増加 => 読み手が問題を抱えている可能性が高い

複数のメトリクスを組み合わせることで、より詳細な問題発見につながる可能性がある。
この辺りは、監視と同じ。

評価の際は、フィードバック情報も参考にすると良い。
具体的な問題について、より多くの背景情報が得られる可能性がある。

10章 ドキュメントの構成

サービスの成長に伴い、ドキュメントも増加する。
ドキュメントが増加していくと、未整理、または不適切な配置のドキュメントも現れる。
未整理、不適切な配置のドキュメントを整理し、構成を組み立てなおす必要がある。

"ドキュメントに適用する構成上の組み立て" を、 ドキュメントの情報アーキテクチャと呼ぶ。

ドキュメント構成のゴールは、以下の通り。

ーザーが必要な情報を見つけるのに役立ち、
管理者が長期間にわたって保守・スケールで切るような、
コンテンツにとって最適な構成上の組み立てをつくること。

イメージは、駅や空港の地図。

以下の情報をドキュメントに組み込むことで、読み手が、コンテンツのメンタルモデル（コンテンツ構成のイメージ）を作れるよう支援する。

• サイトナビゲーションと構成
• ランディングページ
• ナビゲーションの手がかり

また、プロダクトとドキュメントの進化に合わせて、サイトに対するユーザーのメンタルモデルを検証し、改善に努めること。

サイトナビゲーションと構成

サイトナビゲーションは、現在のコンテンツの地図と将来追加されるコンテンツの予定図の両方を示す。
コンテンツ整理の主要な方法は、以下の3つ。

• シーケンス（順序構造）
• 階層（ピラミッド構造）
• Web （階層構造を持たない、相互リンク構造）

扱う情報に合わせて、上記方法を組み合わせて情報アーキテクチャを構築する。

• チュートリアルや手順書はシーケンス、ノウハウ集は相互リンク、ランディングページは階層...など

ランディングページ

「最小限の文章量で、適切なコンテンツへとユーザーを誘導する」ことを目的としたページ。
道路上で進行可能な方向を指し示している大きな標識に相当する。

ユーザーにとって、最も重要で関連のある情報は、強調しつつランディングページに乗せると良い。
ランディングページに載せるコンテンツを決める場合、ユーザー調査の結果（1章）と会社の戦略目標は良い参考情報になり得る。

ランディングページがごちゃごちゃしてはならない。
ランディングページに乗せるコンテンツは、ユーザーにとって最も重要である情報に制限すること。

ナビゲーションの手がかり

コンテンツのほかの部分と、読み手の現在位置を比較できるような情報。
迷子になりつつある読み手に現在位置を示しつつ、次に向かうべき場所を知るきっかけになる。

ナビゲーションの手がかりには、以下の要素がある。

• パンくずリスト
• 再度ナビゲーション
• ラベル止めたデータ
• 「前提条件」、「次のステップ」、「追加の情報」といった、関連情報へのリンク
• 間違ったページに迷い込んだ読み手向けの脱出口（「ホーム」など）

ドキュメント再構成にあたって

以下の質問を投げかけ、既存のコンテンツを評価する。

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

評価に応じて、ドキュメントへの対応を表す、以下のようなラベルを付与しておく。

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

評価後、「ユーザーは欲しがっていたけれど、リストに書いていない情報はあった？」と自問自答し、コンテンツのギャップを探索する。
発見したギャップが小さくなるよう、コンテンツを再構成していく。

特に、再構成に当たって、読み手は以下を期待する。

• 一貫している
  • 構造に一貫性があり、目的の情報の配置場所が予測しやすい
• 関連している
  • 目的の達成に役立つ、最も重要なドキュメントをすぐに発見できる
• 見つけやすくなっている

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

ドキュメントに記載された情報が不正確だと、ユーザーはドキュメント、および製品への信頼を失う。

ユーザーが目的を達成できるよう、ドキュメントを保守していく。

保守計画

ドキュメントの保守に当たり、コードとドキュメントの整合が必要。
整合を取るためにも、保守計画を立てる。

コード、およびドキュメントの変更が、ユーザーへ与える影響を分析する。

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

リリースプロセスの中に、ドキュメントの保守作業を組み込むと、整合を取りやすい。

ドキュメントの変更に責任を持つ、ドキュメントオーナーを明示的に任命し、責任の所在を明確にする。
これにより、ドキュメントが古くなることの防止につながる。
そして、コンテンツの保守を担当している開発者に報いること。

ドキュメントの保守は必要な作業である、「余分な」もしくは「追加」の作業と考えてはならない。

• リリースプロセスの計画段階から、ドキュメントの保守工数を見積もりに追加しておくとよさそう

保守の自動化

トイルを根絶する目的で、保守作業を自動化する。

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

主な保守作業は以下の通り

• コンテンツの鮮度確認
  • コンテンツの最終更新日を確認する
  • 古いドキュメントを発見したら、記述に問題が無いかレビューを行う
• リンクチェッカー
  • ドキュメントに記載されているリンクが、リンク切れを起こしていないか確認する
  • ツールで十分確認可能
    • デプロイ前 : CI/CDにリンク検査プロセスを組み込む
    • デプロイ後 : 公開後のドキュメントに対して、クローラーを使用して検査
• リンター
  • 誤字脱字、怪しい構文を自動検出・修正する
• リファレンスドキュメント生成
  • 可能な場面であれば、リファレンスドキュメントを自動生成する
  • => API ドキュメントであれば、OpenAPI書き出しなど

ドキュメントの非推奨化

サービスの成長に伴い、コンテンツが非推奨化することは十分あり得る。

誤った情報をユーザーに伝えないためにも、
コンテンツの非推奨化に合わせて、関連ドキュメントにも、コンテンツが非推奨である旨を記載する必要がある。

基本的には、APIを非推奨化するプロセスと同じ要領で、関連ドキュメントも非推奨化する。

今後非推奨となる事項をユーザーに告知する...という方法もある。
以下の方法が考えられる。

• リリースのお知らせやリリースノートの中で、非推奨機能の一覧を書きだす
• ドキュメント内に、非推奨機能の一覧を書きだす

ドキュメントの削除

原則として、ドキュメントは、ユーザにとって不要になった時点で削除する。
「不要になった時点」

• 非推奨APIの移行が完了し、非推奨APIの利用者が0であることを確認できた場合
• 陳腐化・無関係化したドキュメントが存在し、その修正工数が割に合わない場合

不要な情報が減ると、ドキュメントを探索する読み手は、その分迷子になりにくくなる。

削除の前に、事前にユーザーに知らせるべき。
その際、リリースノートにて、機能削除と併せて告知すると効果的。