### ドキュメントをなぜ書くのか？を考える
誰のためのドキュメントなのか、その誰に対してどういう期待をしているのか、によって内容は変わってくる。
ドキュメントに落とし込む場合、以下を土台にして構成を考えていくのが良い。
> 「ある読み手」が「ある目的」を達成するために、「ある活動」をしたい
また、ドキュメントの効果や影響も考慮しておくと良い。上級エンジニア向けはより細かく詳細を書く方が好まれるし、初級エンジニア向けには学習曲線が急カーブするガイドが好まれたりする。そして、そのドキュメントを必要としている人の多さによって作成作業のコストパフォーマンを考える。
### ドキュメント作成時の心構えも大事
・見出しは重要
読者は頭から全部読まない。ざらっと斜め読みして気になった単語を見つけて周辺を読み込むという動きをすることが多いため。統計的に流し読みの場合、良くても全体の２８％しか読まない。
・ドラフトは完璧を目指さない
編集する前提で書いていく。編集を積み重ねることで「複雑性を減らせる」
・フィードバックはすべて取り込む必要はない
逆に相手にフィードバックする際は建設的な提案ができるときだけ批判しよう（プラッシング @ピクサー）
### ドキュメントの種類
・コードコメント
コメントはコードから読み取れない有用な情報やコンテキストを把握するのに役立つ。また、過去の意思決定を残しておく意義は大きい。
コードベースが成長するにつれて背景が不透明化して判断に迷うことがあるため。
コードが自己文書化するし、コメントのメンテコストを嫌うエンジニアもいる。
コードは完璧にならないし、自分が１ヶ月前に書いたコードを後で見返した時にちゃんと背景を覚えているか怪しいことを再認識してみるのが良い
・README
リポジトリにおけるチートシート
・スタートガイド
ユーザー向け。
・コンセプトドキュメント
サービスがどのようにユーザーに機能するかを説明するもの
・手順書
チュートリアルやハウツーガイド
構造化された手順に従うことで特定のゴールを読み手が達成できるもの
たくさんのステップは情報量が多すぎて複雑になり、ミスを誘発するため、長い説明は避ける。数行の説明と画像の利用が効果的。
・リファレンス
原因と結果を扱うもの。トラブルシューティング時に有効。
無料のKindleアプリをダウンロードして、スマートフォン、タブレット、またはコンピューターで今すぐKindle本を読むことができます。Kindleデバイスは必要ありません。
ウェブ版Kindleなら、お使いのブラウザですぐにお読みいただけます。
携帯電話のカメラを使用する - 以下のコードをスキャンし、Kindleアプリをダウンロードしてください。
何か問題が発生しました。後で再度リクエストしてください。
よく一緒に購入されている商品
+
+
総額:
当社の価格を見るには、これら商品をカートに追加してください。
ポイントの合計:
pt
一緒に購入する商品を選択してください。
この商品をチェックした人はこんな商品もチェックしています
ページ 1 以下のうち 1 最初から観るページ 1 以下のうち 1
出版社より
～ 本文より ～
