「その機能はあの人しか分からない」「仕様書はあるが古くて当てにならない」——開発が属人化している現場では、たいていドキュメントに問題があります。ドキュメントが無いか、あっても更新されず形骸化しているかのどちらかです。

かといって、何もかもを文書化しようとすると、書く負担と更新負担で結局続きません。大事なのは、「最小限で、更新され続ける」ドキュメントを設計することです。この記事では、属人化を防ぐドキュメント整備を、優先順位づけから運用ルールまでの手順で解説します。自走できる開発体制づくりの全体像は開発を内製化する進め方、外部メンバーの立ち上げに効くドキュメントは外部エンジニアのオンボーディング設計も参考になります。

なお筆者・馬込は、参画先で形骸化していた社内ノウハウを集約し、公式ドキュメントとして体系化した経験があります。本記事はその実務目線でまとめています。

結論：全部書かない。「詰まる箇所」から最小限を整える

ドキュメント整備の失敗は、たいてい「網羅しようとして続かない」ことから起きます。目指すのは完璧な網羅ではなく、人が入れ替わっても開発が止まらない最小限です。①優先順位づけ → ②最小限を書く → ③更新され続ける運用、の順で進めます。

手順1：ドキュメント化する対象を優先順位づけする

すべてを書く前に、「無いと困る順」に並べます。判断の軸は、参照頻度が高く、口頭説明のコストが大きいものです。

優先度 ドキュメントの例 理由
高 環境構築手順、デプロイ手順 頻出・つまずくと止まる
高 アーキテクチャ概要、主要な設計判断 判断の背景が失われやすい
中 コーディング規約、レビュー基準 品質の均一化に効く
低 個別機能の詳細仕様 変化が速く陳腐化しやすい

個別機能の細かい仕様まで書き込むと、変更のたびに陳腐化して形骸化の温床になります。変わりにくく参照頻度が高いものから整えるのが定石です。

手順2：最小限で「読めば動ける」粒度に書く

優先度の高いものから、最小限の粒度で書きます。目的は美しい文書ではなく、読んだ人が実際に動けることです。

  • 環境構築・デプロイは、上から順になぞれば再現できる手順書にする
  • 設計判断は「なぜそうしたか（背景・却下案）」を一行でも残す
  • 完璧を待たず、まず7割で公開して使いながら直す

特に「なぜそうしたか」は、コードを読んでも分からず、口頭でしか伝わらない情報です。ここを残すだけで、属人化はかなり防げます。

手順3：更新され続ける運用ルールにする

書いて終わりにせず、更新が回る仕組みにします。「更新しない」を前提に、更新の手間を最小化するのがコツです。

  • 変更のプルリクエストに、関連ドキュメントの更新を含めるルールにする
  • 置き場所を一箇所に集約し、探す手間をなくす
  • 古くなった記述は消す。「間違った情報が残る」より「無い」ほうが安全な場合もある

更新負担が重いと、どんな良いドキュメントも形骸化します。書く量を絞り、変更と同じ流れで更新される導線を作ることが、継続の鍵です。

手順4：「誰が・いつ書くか」を決める

ドキュメント整備が続かない原因の多くは、内容の問題ではなく書く人とタイミングが決まっていないことにあります。「手が空いたら書こう」は、ほぼ確実に書かれません。開発は常に忙しく、手が空く日は来ないからです。

そこで、書く人とタイミングを仕組みに埋め込みます。

何を 誰が いつ
環境構築・デプロイ手順 その作業を最初に通した人 通した直後（記憶が新しいうち）
設計判断の背景 判断した本人 判断したその場（後から思い出せない）
つまずいた箇所 詰まった本人 解決した直後

共通するのは、**「その情報が生まれた瞬間に、その人が書く」**という原則です。後からまとめて書こうとすると、背景を思い出せず、内容も薄くなります。逆に、判断した瞬間に一行残すだけなら、負担はほとんどありません。

もう一つ有効なのが、新しく入った人に書いてもらうことです。長くいる人には「当たり前すぎて書く発想が出ない」ことが、新しい人には見えます。詰まった箇所をその人自身に追記してもらえば、次に入る人が同じ場所で詰まらなくなり、ドキュメントが実際の詰まりどころに沿って育っていきます。

よくある落とし穴

  • 網羅しようとして続かない：全部書こうとすると負担で止まります。詰まる箇所から最小限に。
  • 細かい仕様を書き込みすぎる：変更で陳腐化し形骸化します。変わりにくいものを優先。
  • 「なぜ」を書かない：手順だけ残すと、判断が必要な場面で結局人に聞くことになります。背景を一行でも残します。
  • 置き場所が分散する：探すのに手間がかかり、参照されなくなります。一箇所に集約します。
  • 「手が空いたら書く」で先送りする：開発が忙しく、その日は来ません。情報が生まれた瞬間に、その人が一行残す運用にします。

よくある質問

Q. ドキュメントツールは何を使えばいいですか？ A. ツールより「一箇所に集約され、変更と同じ流れで更新される」ことが重要です。チームが日常的に開くツールに置くのが基本で、コードに近い情報はリポジトリ内に置くと更新が回りやすくなります。

Q. 忙しくてドキュメントを書く時間が取れません。どこから始めますか？ A. 「新しく入った人が必ず詰まる箇所」から一つだけ始めるのがおすすめです。環境構築手順など、頻出でつまずきやすいものから整えると、質問対応の時間が減り、その分を次のドキュメントに回せます。

Q. どのくらい書けば属人化は防げますか？ A. 網羅は不要です。「その人が休んでも、他の人が手順をたどって開発を進められる」水準が一つの目安です。完璧な仕様書より、動ける最小限のほうが継続し、結果的に属人化を防ぎます。判断に迷ったら、「この人が明日から1週間不在になったら、何が止まるか」を書き出してみてください。止まるものが、そのまま最初に書くべきドキュメントの候補になります。逆に、止まらないものは後回しで構いません。

開発ドキュメントの整備は、①詰まる箇所から優先順位づけ ②読めば動ける最小限を書く ③変更と同じ流れで更新、という進め方なら、負担を抑えて属人化を防げます。全部書くのではなく、最小限を更新し続ける。これが形骸化しないドキュメントの作り方です。

属人化の解消や開発体制づくりの相談は、開発支援について相談するからお問い合わせください。