やったこと

• 書籍「エンジニアのためのドキュメントライティング」 PART2 (3,4,5,6章) 読了

学んだこと

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

白紙のドキュメントの冒頭に、「読み手、目的、コンテンツパターン」を書くところからスタート。

タイトルを決める

「読み手、目的、コンテンツパターン」が決まると、タイトルを決定できる（特に「目的」は有用）。

• タイトルを見た瞬間、ゴールがイメージできるようなフレーズにする
• そのため、キュメントのゴールは一つに絞ること
  • 複数のゴールが存在する場合、ゴールが一つになるようドキュメントを分割すること

アウトラインを作る

読み手が、タイトルに書いたゴールを達成するために、読み手が知っておくべきこと、やるべきことを考え、必要な手順を列挙する。

• ゴールを達成するために、ゴールをサブタスクに分割するイメージ

正しいタイミングで、正しい情報を読み手に提供できるよう、アウトラインを修正する。

• 順序を変える
• （必要に応じて）項目を追加・削除・変更する
• 複雑すぎる場合、項目を分割する

以下の質問を自身に投げかけ、アウトラインをレビューする。

• 追記すべき事前情報や設定情報はあるか？
• 飛ばしている手順や、説明が不完全な手順は無いか？
• 手順は合理的な順で並んでいるか？

アウトラインに自信が持てたら、アウトラインの項目を肉付けしてく。

流し読みに対応する

大多数の読み手は、必要な情報を求めてドキュメントを流し読みする（F 型）。
流し読みする読み手を想定し、必要な情報を見つけやすくすることは重要。

流し読みする読み手に役立つコンテンツ作りの戦略は、以下の通り。

• 最も重要な情報を冒頭で述べる
  • ドキュメントのゴールを要約して、タイトルに設定する
• 大きな文章の塊を分割する
• 複数の長文ドキュメントを分割する
• 簡潔さと明確さに向けて努力する
  • 「このコンテンツで読み手のニーズを満たせているか？」と問い、改善に努める

ドラフト作成に行き詰ったら

• 完全主義からの脱却
  • かけるところから書く
• 周りの人に、助けを求める
• 足りないコンテンツを強調する
  • 書けない（重要な情報が欠けているなど）箇所は、TODO, T.B.D. などと書いていったんスルー
  • 確信をもって書ける部分から書いていく
• 順不同で書く
  • 書けるところから書く
• メディア（ツールや手法など）を変える

ドラフトを完成させる

以下、ドラフト完成のチェックリスト。

• [ ] 大見出しはドキュメントのゴールを要約しているか？
• [ ] 複数の見出しによってドキュメントは十分に要約されているか？
• [ ] ドラフトは最初から最後まで読み手のニーズにこたえているか？
• [ ] 情報の流れは読み手に取って理解しやすいものか？
• [ ] 何らかのドキュメントパターンやテンプレートに正しく従っているか？
• [ ] 全手順が動作することをテストし確かめたか？

4 章 ドキュメントの編集

ここで言う編集とは、ドキュメントを見て、ユーザーニーズに応えているか確認するプロセス。
レビューや評価といった、分析的なプロセスではない。

編集方法

編集プロセスを一連の複数の周回に分解して、一つの周回で一つの観点に絞って編集すると良い。

• 編集速度が向上する

開発者向けドキュメントだと、以下の観点で編集を周回すると良い。

• 技術的な正確さ
  • 観点
    • 指示通りに作業すれば、ドキュメントに記載された結果が得られるか？
    • 技術的な専門用語、もしくは混乱しやすい用語はあるか？
    • コードの関数、パラメータ、エンドポイントは正しく命名され、説明されているか？
  • 手順があれば、指示通り実行して、うまくいくことを確認すること
  • 手順に制約条件があれば明記する事
• 完全性
  • 観点
    • TODO, T.B.D. が無いこと
    • コンテンツにギャップが無いか
  • OS 上の制約や情報の有効期限があれば記載する
• 構成
  • 観点
    • タイトルと見出しから、何について書かれたドキュメントか明確になっているか？
    • ドキュメントは、一貫性のある、論理的な方法で構成されているか？
    • 他のドキュメントに配置すべきセクションは無いか？
    • テンプレートが存在するならば、テンプレートに従って書かれているか？
  • 一貫した構成は、予測が可能となり、読み手が適切な部分にたどり着きやすくなる
  • 読み手がコンテンツを読む前後にすべきことが無いか確認する
    • 読み手は、前後のドキュメントを読まず、いきなり特定の章から読み始めることが少なくないため
• 明確さと簡潔さ
  • 不自然な表現は書き換え、重複情報を削除し、不要な言葉を取り除く
  • コンテンツはできる限り短くし、要点を絞る
  • さしずめ、ドキュメントに対するリファクタリング

ドキュメントレビュー

自身でレビューする場合、以下のチェックリストを使用する。

• [ ] タイトルが短くて具体的である
• [ ] 見出しは論理的に並べられており、一貫性がある
• [ ] ドキュメントの目的が最初の段落で説明されている
• [ ] 手順はテストされていて動作する
• [ ] 技術的なコンセプトが説明されている、もしくはリンクされている
• [ ] テンプレートの構成に従っている
• [ ] リンクがすべて有効である
• [ ] 誤字脱字・文法チェックツールが実行されている
• [ ] グラフィックや画像が明確で有用である
• [ ] 前提条件や次のステップが定義されている

他のメンバーにレビューを依頼する場合、レビューの観点を伝えること。

• 構成をレビューしてほしいのか？技術面なのか？明確さと簡潔さを見てほしいのか？ など

また、フィードバックの受け取り方も合意しておくこと。

場合によっては、専門家にレビューを依頼する（=>テクニカルレビュー）

もらったフィードバックを取り入れる

ドキュメントのゴールは、知識を読み手に効果的に伝えること。
フィードバックは、非難ではなく、より効果的に伝える方法を指摘するものだと捉える。
矛盾したフィードバックがある場合、「ユーザーがこのドキュメントを読んで達成したいこと」、つまりはゴールを満たすことに繋がるフィードバックを優先する。

• どのみち、全てのフィードバックに対応するのはリソース的にも困難となりやすい

良いフィードバックを提供するためには、以下を守る。

• フィードバックの際は、「人」ではなく、「アイデア」に集中する
  • 「あなたが間違っている」ではなく、「この部分が不明確だ」といった具合
• 批判に続けて、建設的な代替案を出す
• フィードバックに反応するための時間を確保する

また、フィードバックでは素晴らしかった部分を伝えてもよい。
素晴らしい文章を共有することで、他の人がまねできるようになる。

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

良いサンプルコードは、文章で説明する以上に多くの情報を読み手に提供できる。

サンプルコードは、一般的に「説明用」と「実行可能なもの」の二種類存在する。

• 実行可能なサンプルコードは、コピペ（かつ必要に応じて改変）して実行できるコード
• 説明用のサンプルコードは、読み手の理解向上や、読み手の環境での実行結果を比較する目的で使用するコード

良いサンプルコードの原則

読み手は、サンプルコードが（可能ならコピペしてそのまま）動作することを期待する。

そんな、良いサンプルコードは、以下の原則を満たすべき。

• 説明されていること
  • サンプルコードのそばに、コードの必要性を説明したコメントが存在すること
  • コードを動かすために必要な前提条件が、全て説明されていること
    • 制約などがあれば、きちんと書くこと
• 簡潔であること
  • 読み手が必要とする、過不足ない量の情報が提供されていること
• 明確であること
  • 読み手が期待する言語習慣に従ってサンプルコードが書かれている
  • 読み手が混乱しないよう、複雑なテクニックは避ける

加えて、実行可能なコードは、以下の原則を満たすべき。

• 利用可能（であり拡張可能）であること
  • パラメータの置き換えが必要な場合、置換用データを説明する
  • 何で置き換えればよいのか一目でわかる変数を使用すること
    • your_password や replace_with_actual_xxx など
• 信頼できること
  • ペースト可能であり、動作し、余計なことを実行しない

サンプルコードの設計

サンプルコードの設計に当たっては、以下の点を留意する。

• 読み手になじみがあって、最も使われそうな言語を選んで、サンプルコードを作成する
• 快適さ・理解度合いに幅がある読み手をサポートするため、様々な複雑さのサンプルコードを提供する
  • 初心者向けだと、 hello_world レベル
  • 習熟した読み手向けだと、 特定のユースケースに特化したサンプルコードなど
  • 入門者向けドキュメントと、熟練者向けドキュメントを混同しないよう注意すること
• コードだと一目でわかるような、一貫したスタイルでサンプルコードを提供する
  • Markdown なら バッククォート がメジャー

その他、サンプルコードに関する Tips

• 実行可能なコードは、動作確認しておくこと
• 場合によっては、読み手が自由にコードを試せるサンドボックスを提供する
  • 多くのユースケースでは過剰な選択
• サンプルコードを自動生成する
  • 背景説明といった文脈が必要な場合、人手によるコメント追加も行うこと

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

" 百聞は一見にしかず " 。

ビジュアルコンテンツはドキュメント補助が目的。
ドキュメントの代替にはなり得ない。

ビジュアルコンテンツの目的は、ドキュメントの理解促進であり、これに寄与しない情報は全て邪魔、ぐらいに思っておくこと。

• 読み手の必要とする情報と、作り手の好みは、異なることが多い

ビジュアルコンテンツは、以下の三点を満たすことを常に意識する。

• 理解容易性
  • 読み手に役立つ情報であること
• アクセシビリティ
  • 読み手を限定しないこと
• パフォーマンス
  • ビジュアルコンテンツの掲載によって、ドキュメント表示が遅くなり、読み手の時間を奪わないこと

ビジュアルコンテンツも、ドキュメント同様にレビューすること。
その際、上記三点を満たしているかがレビューの観点となる。

ビジュアルコンテンツの例

• スクリーンショット
  • 可能なら、画像が表現している情報を、文章でも表現すると良い
  • 加えて、画像が、さも存在しないようなコンテンツ説明文にすると良い
    • ×「メニュー上部にある小さな歯車の画像」
    • 〇「メニュー上部に小さな歯車があります」
  • コピペが必要になりそうな情報をスクショで提供しないこと
• 図表
  • ボックスと矢印
    • 文書単体では説明が難しい、エンティティ間のデータの流れや関係性をわかりやすく描くことが出来る
    • 使用する図形に一貫性を持たせること
      • 必要なら凡例を記載すること
  • フローチャート
    • プロセスをドキュメントに落とし込むことが出来る
    • 使用する図形に一貫性を持たせること
  • スイムレーン
    • 複数のコントリビューター（もしくはアクター）が存在する状況を表現できる
    • 複数のコントリビューター（もしくはアクター）が存在することを除けば、特徴はフローチャートと同じ

図の目的は " 単純化 "。

• 一つの図で表現するアイデアは、一つに絞ること
• 場合によっては複数の図に分割すること
• 図表の要素には、可能なら、読み手の理解を促進するようなラベルを付与すること
• 色に一貫性を持たせること
  • 基本は、ラベルで情報を伝える
• 可能なら SVG 形式で画像を公開すること

映像コンテンツには注意

映像コンテンツには、以下の問題点があり、総じて高コスト。

• 作成には専門知識が必要であり、素人には難しい
• 修正が困難（≒保守コストが非常に高い）

基本的には、上記問題点によるデメリットが大きい。
数枚の図で大体できないか検討すること。