人々が実際に読むドキュメント

十分な四つの文書

READMEファイル。何であるか、ローカルで実行する方法、テストを実行する方法、誰に聞くか。正確でなければならない——すべてのオンボーディングで確認される文書だ。

アーキテクチャの決定。重要な決定ごとに一ページ：コンテキスト、選択肢、何が選ばれなぜか。短く日付入り。

オペレーション。何かが壊れたとき何をするか、デプロイする方法、ロールバックする方法。

インターフェース。コード自体から、古くならないように。

新鮮に保つ方法

コードの近くに住み、同じマージリクエストで更新されるドキュメント。他の場所の文書は二ヶ月で古くなり、さらに悪いことに——権威あるように見えたまま。

文書化しないもの

コードが明確に言うもの。行を説明するコメントは冗長；珍しいアプローチが選ばれた理由を説明するコメントは金の価値がある。