はじめに
表題の本を読んで得られた知見をまとめる。
想定読者を定める
読者にとって必要なコンテンツをリストアップするために必要なタスク。
- 誰のためのドキュメントなのか？
- 読み手にとって必要な情報は何か？
- プロダクトの利用者からのフィードバックを得る
- ユーザーへの共感
- 読者の背景知識が作者よりも薄い前提で作成する
ドキュメントの計画を作る
ドキュメントの全体像を理解しておく
- ソース内での適切なコメント
- README
- リリースノート
- FAQ
- トラブルシューティング
最初のドキュメントを書く
- リストアップから始める（白紙の状態で書くのは難しい）
- タイトルとゴールから流れに沿って書く
- 適切な書式を使う（見出しやリストなど）
- 流し読みに適した書き方（読者はほとんど読まない）
- 重要な情報を先に書く
- 大きな要素は複数のアウトラインに分割する
- 短くシンプルに
- 最初から完璧を目指さない
- 順不同で書く（書きやすいものからでOK）
ドキュメントのブラッシュアップ
- 正しさ
- 指示通りに動くか？
- 専門用語など使わずわかりやすいか？
- 構成が適切か（見出し単位）
- 明確さ・簡潔さ（文章単位での表現）
- レビューとフィードバックを行う
- アイディアに対して行う
- 建設的な提案を行う
良いサンプルコード
- 説明を加える
- 何のためのサンプルか？
- 前提知識
- 環境変数
- よくあるエラー
- 簡潔にする
- 適切な改行（水平バー、カッコ悪い）
- 無駄なコードを書かない
- コードの明確さ
- リファクタリング
- 変数名・関数名
- 信頼性の高い文章
- 一貫性をもたせる
- サンプルと実態との一致
映像コンテンツ
割愛
以降は必要になったタイミングで追記する予定。
おわりに
常に意識していた部分ではあるけど、より解像度が上がった。
時々読み返して、練度を上げていきたい。