会社の輪読会で『エンジニアが一生困らない ドキュメント作成の基本』を読みました。
ドキュメントを書くときにどういうステップがあって何に気を付けるかが詳しく解説されていて参考になりました。まず、読み手がこのドキュメントをどういう目的で読むのかを想定することが重要。それに合わせて構成を組み立てる。
自分は文章を書くのはどちらかというと好きな方で、あまりドキュメントを書くのを苦に感じたことはない。このブログを書いているのも、半分は文章を書く練習を目的にしている。ただ、これまではわりと自己流で書いてた感じなので、改めてこういうノウハウとして知ることができたのはよかった。
とはいえ、ノウハウを知るのも大事だけど、文章を書くことに慣れることも大事。このあたりはプログラミングも同じかもしれない。
ちなみに、こういうノウハウを解説する系の本を輪読会で読んでも、なるほどね〜くらいで話が終わってしまうことがあるような気がする。一方で、設計手法やアーキテクチャのようなテーマだと、個人の思想や過去の経験によっていろいろな解釈が生まれて議論に発展したりして、そこから得る学びも多い。
あと、本書では語彙力はなくてもいいと書かれてるところがあったけど、個人的には語彙力は重要だと思う。ないよりはあった方がいいとかではなく。読み手に合わせて表現を変えたいときに、語彙力がないと適切な言い換えが出てこないし、そもそも、語彙力が不足していると読み手に合わせて表現を変えたいという発想にならない気がしている。
以下、読書メモ。
Chapter1
感想 / 意見 / その他
- ドキュメントを書く目的
- 説明型 (知見や手順を説明する)
- 報告型 (知見や活動を報告する)
- 説得型 (意見や提案を伝えて相手の行動を促す)
- バックログを要件定義書の代わりと捉えるのはなるほど
- プロダクトが満たすべき要件をユーザー視点で説明する
- ドキュメントの種類ごとにテンプレートを使う
- 設計のコンフルは過去のものを使い回したりしてる
- 想定読者を絞り込む
- 目的で絞り込む (ex. トラブルシューティング)
- 知識レベルで絞り込む (ex. 初心者向け)
- 立場で絞り込む (ex. システム管理者向け)
- テーマを分解する
- なぜ (Why) / 何を (What) / どうやって (How)
- 具体例か構成要素のいずれかで分解する
アイデア / 今後こう生かせそう
- ドキュメントを書く前にどの分類のドキュメントかを明確にする
- タスクを作成する際はユーザー視点でのゴールを書く
- ドキュメントを書くときは目次 (TOC) を付けよう
- 語彙に敏感なろう (語彙に敏感になると誤字脱字にも敏感になると思う)
Chapter 2
感想 / 意見 / その他
- ドキュメントの階層構造を理解すると効率よく読める
- タイトル, 見出し, リード文, パラグラフ, 中心文
- 階層構造はいいけど同階層の粒度を揃えるのがキモになりそう
- パラグラフごとに1つの言いたいこと (+ 理由や説明) を書く
- 言いたいこと = 中心文
- 辞書形式, 読み物形式
- 中心文をパラグラフの冒頭に書く
アイデア / 今後こう生かせそう
- 階層構造の階層を行ったり来たりして俯瞰しながら粒度を揃えるといいと思う (おそらくトップダウンでスムーズに最下層まで書き出せることはそれほど多くないのかもしれない)
- ドキュメントが検索にヒットしやすいようにするとよさそう (いい感じにキーワードを含めたりコンフルだとタグとかラベルとか付けたらよさそう？)
Chapter 3
感想 / 意見 / その他
- 読者を理解する
- 知識レベル
- 目的
- 立場や役割
- 読者の目的を絞ることで読者に合わせた構成を組める
- 機能別, 用途別, ...
- 誰に何を伝えようとしているのか
- 知識は3つに分類できる
- プロダクトに関する知識
- 技術に関する知識
- 業務に関する知識
- ドキュメントの階層は4階層に収める
- タイトル, 章, 節, 項
アイデア / 今後こう生かせそう
- ドキュメントを書く前に想定される読者と目的を明確にする
- 知識の分類による絞り込みはよさそう
- 構成を考える際にページを分割できるかどうかを考える
- あるテーマに対して複数の目的 (用途) があるならページを分割する
Chapter 4
感想 / 意見 / その他
- テーマを分解する
- タイトル, 見出し, パラグラフ
- テーマ, サブテーマ, 話題
- 読み手が納得感を得られるように
- 適切な分解方法は読み手によって変わる
- 情報を探しやすい構成になる
- 読み手はタイトルや見出しから当たりを付ける
- なぜ (Why) / 何を (What) / どうやって (How)
- 構成要素で分解する (全体から部分へ)
- 機能の構成要素で分解する
- 機能の用途や使い方を知りたい
- 具体例で分解する (概要から詳細へ)
- 利用目的で分解する
- 自分の目的をどうすれば達成できるのか知りたい
アイデア / 今後こう生かせそう
- 3つの型 (説明型, 報告型, 説得型) ごとの なぜ, 何を, どうやって の具体例が分かりやすい
- タスク起票するときも why, what, how で書くことある
- 説得型はさらに when とか how much とか分けてもよさそう
- 構成要素による分解と具体例による分解を組み合わせたい場合は、先に構成要素で分解したドキュメントを作成しておいて、具体例が関連している構成要素を参照させる形がよさそう
Chapter 5
感想 / 意見 / その他
- 急がばアウトライン
- アウトラインを笑う者はアウトラインに泣く
- アウトライン
- なぜ, 何を, どうやって
- 何をとどうやってはどちらを先に書くか
- 読み手にとって重要なものから書く
- 順列
- 内容に依存関係や順序関係があるか
- 既知から未知へ
- 時系列
- 並列
- 重要度
- ニーズの大きさ
- ゴールデンサークル理論
- なぜ, どうやって, 何を
- なぜから先に読み手に伝える
- 書けるところから先に書くことで知識や考えが整理できる
- 書く内容が多い要素や重要な要素には見出しを付ける
アイデア / 今後こう生かせそう
- 見出しを簡素に書きたくなるが、簡素にしようとすると見出しの抽象度が上がって結果的に本文の内容が膨らみがち
- もう少し本文の内容を表す見出しにして本文もコンパクトにしていきたい
Chapter 6
感想 / 意見 / その他
- パラグラフ
- 言いたいこと (中心文) + 理由/説明/具体例 (支持文)
- 理由/説明/具体例で読み手の納得を得る
- 結論文で言いたいことを強調する
- 理由や詳しい説明が必要な要素だけにパラグラフを割り当てる
- 内容が少ないものは1つのパラグラフにまとめる
- 並列の情報は表現を揃える
- 箇条書きも同様 (文末や句点ありなしを揃える)
アイデア / 今後こう生かせそう
- 中心文に対してどういう支持文 (理由/説明/具体例) を付け加えるか
- 読み手の前提知識やドキュメントの目的次第？
Chapter 7
感想 / 意見 / その他
- 日本語スタイルガイド
- 重要なことから書く
- 読み手の視点で書く
- 読み手にとってどのような価値があるか, どのような影響があるか
- 能動態と受動態を使い分ける
- 読み手の視点
- 一文一義
- 箇条書きも有効
- むやみに箇条書きを多用しない (重要な情報に絞る)
- 係り受けを明確にする
- 通俗的な表現わりと好き (もちろん内部向けのドキュメントだけど)
- 明確で簡潔で具体的な文章を書くにはやはり豊かな語彙は必要だと思う
アイデア / 今後こう生かせそう
- 係り受けを明確にする
- 読点を多用すると歯抜けな文章になりがちなのでまずは語順を入れ替えて明確にできないかを試すといいと思う
- 書いた文章を読み直す習慣を付けましょう
Chapter 8
感想 / 意見 / その他
- 生成 AI の出力結果をどう評価するのかが分かりやすくて参考になった
- この前、全社に流したリリースアナウンスは ChatGPT に書いてもらった
- 文章と箇条書きをバランスよく使い分けてくれてよかった
- 合成名詞を多用しない
- 情報の構造化が大事
- 文章の校正で修正箇所を太字にできるの知らなかった
- どこが変わったのかが分かりやすくなっていい
アイデア / 今後こう生かせそう
- 文章を書くときは生成 AI を通すのを標準にしてもよさそう
