ドキュメントは『未来の自分とチームへの贈り物』
良いドキュメントは、自分自身と将来のチームメンバーへの最大の投資です。本記事では、エンジニアが書く主要ドキュメントの作法を編集部の視点で整理します。エンジニアのコミュニケーション力、エンジニアの質問力 もご参考に。
主要なドキュメント種別
(1) README：プロジェクトの入口。(2) 設計書：アーキテクチャ・データモデル。(3) ADR（Architecture Decision Record）：意思決定の記録。(4) ランブック：運用手順。(5) API リファレンス：開発者向け仕様。APIマネタイズ戦略、GitHubポートフォリオの作り方 もご参考に。
README の構成
(1) 1文での説明：「○○を○○するツール」。(2) クイックスタート：3分以内で動く。(3) 主要な機能：箇条書きで簡潔に。(4) 使い方の例：コピペで動くサンプル。(5) 開発者向けセクション：貢献・ライセンス。OSSプロジェクトの立ち上げ戦略 もご参考に。
設計書の書き方
(1) 目的：何を解決するか。(2) 制約と前提：守るべき条件。(3) 選択肢の比較：他の案も検討。(4) 決定とその理由：選んだ案と根拠。(5) 図解：アーキテクチャ・データフロー。Webの基礎を学ぶロードマップ もご参考に。
ADR の活用
(1) 意思決定を1ページに残す：「なぜ X を選んだか」。(2) 採用したもの・しなかったもの：選択の透明性。(3) 影響範囲：他システムへの影響。(4) 変更履歴：後で見直せる形に。(5) 誰が決めたか：責任の所在。ADR は新規参画者のキャッチアップを大きく加速します。
ランブックの作り方
(1) 状況：いつ使うか。(2) 手順：番号付きステップ。(3) コマンド・スクリプト：コピペで動く形。(4) 判断基準：どこで止まるか。(5) 連絡先：エスカレーション先。SREへの転身ガイド もご参考に。
ドキュメントの保守
(1) コードと一緒に管理：リポジトリ内に置く。(2) 変更時に更新する文化：PR で必須。(3) 古い情報は削除：間違いの方が無情報より害が大きい。(4) 検索可能に：適切な見出し・タグ。(5) 使われ方の観察：閲覧数等で需要を把握。Notion AIの実務活用 もご参考に。
AI による執筆支援
(1) 下書きの自動生成：構成案・項目出し。(2) 表現の磨き込み：硬すぎる文章の調整。(3) 多言語対応：英訳・和訳。(4) 事実確認は人が：AI に丸投げしない。(5) ブランドトーンの統一：プロンプトに規約を入れる。生成AIを活用した学習法、エージェント型コーディングツール もご参考に。
失敗しがちなパターン
(1) 書いて満足：更新されず古くなる。(2) 長すぎる：読まれない。(3) 図がない：理解に時間がかかる。(4) 専門用語のみ：新規参画者が困る。(5) 『なぜ』が抜ける：意図が伝わらない。対策は、(1)継続更新、(2)簡潔、(3)図解、(4)用語の補足、(5)意図を残す、です。IT・Web業界の職種完全マップ もご活用ください。