【IT現場の生態系】ドキュメントは誰のために書くのか

　深夜二時、静まり返ったオフィスで一人、ディスプレイを見つめています。画面の中には、三年前の自分が書いたはずのプログラム。しかし、今の私にはそれが、未知の文明が残した謎の呪文にしか見えませんでした。

　　「何なんだ、これは」

　思わず独り言が漏れてしまいます。
　助けを求めて、隣にある「仕様書（仮）」と名付けられたフォルダを開きました。しかし、そこに並んでいたのは、中身が一行も書かれていない真っ白なファイルたち。その空虚さに、背筋が寒くなるような絶望を覚えたのです。

　かつての私は「忙しいから」と、未来の自分への伝言をサボっていました。　

　ITの現場では、ドキュメント作成はしばしば「最も後回しにされる仕事」になりがちです。
　動くものが正義の世界において、文字を書く時間は無駄に思えるのかもしれません。
　しかし、熟練のエンジニアたちは、まるでお経のように「ドキュメントを残せ」と繰り返します。彼らは知っているのです。ドキュメントこそが、この過酷な生態系を生き抜くための装備であることを。

　IT現場のドキュメントには、いくつかの顔があります。

　たとえば、顧客と結ぶ要件定義書は、お互いの領土を侵さないための「平和条約」のようなものです。
　これがないと、プロジェクトという国はすぐに紛争に巻き込まれます。

　また、コーディング規約はチームという群れを統率する「生存本能」であり、テスト結果の証跡は、不具合という名の事件が起きた際のアリバイ工作に他なりません。

　さらに過酷な場面、システム障害という嵐に巻き込まれたとき、保守・運用マニュアルは暗闇を照らす「救助信号」に変わります。

　あるいは、先人たちが残したWikiのTipsは、密林を切り拓くための「知恵の継承」です。

　これらが欠けた生態系は、一度のトラブルで全滅する脆さを秘めているのです。

　ここで少し視点を変えてみますす。
　ドキュメントは、本当に「他人のため」に書くものなのでしょうか。

　ドキュメントの本質は「時間旅行」にあるのかもしれません。
　私たちが書く言葉の宛先は、実は今の同僚ではなく、数ヶ月後の自分自身なのです。

　記憶というのは、思っている以上に頼りないものです。
　三ヶ月も経てば、当時の苦労も、あえて回り道をした理由も、綺麗さっぱり忘れてしまいます。
　ドキュメントを書くという行為は、未来で迷子になる自分に向けて「ここは右に曲がれ」と地図を描き、パニックになっている自分に「まずは深呼吸しろ」と指示を送る、時空を超えた救済措置なのです。

　ドキュメントを疎かにすることは、未来の自分やチームの足元に、静かに時限爆弾を埋めるようなものです。
　逆に、たった数行でも「なぜこう決めたのか」が記されていれば、それは未来の時間を買い戻すための、最も利回りの良い投資になります。

　結局のところ、ドキュメントとは「優しさ」の形なのかもしれません。
　後任の誰かが、あるいは未来の自分が、暗闇の中で立ち尽くさないように灯火を置いておく。その小さな気遣いが、IT現場という複雑な生態系を、今日も静かに守っています。

　明日の自分が、今の自分のコードを見て「誰だ、こんな素晴らしいヒントを残してくれたのは」と感謝する。そんなささやかな奇跡のために、今日、一行だけ、未来への手紙を添えてみませんか。

　それは、自分への一番安上がりで、一番温かい贈り物になるはずです。

【開発現場で使用するドキュメントの例】

　IT現場において、ドキュメントは単なる記録ではなく、「情報の血流」や「生存のためのルール」のような役割を果たしています。
　これらを役割やフェーズごとに整理してみました。

1. 開発の指針となる「設計・定義系」

　プロジェクトの骨組みを作るためのドキュメントです。
　ここが崩れると、後の工程で「生態系」が混乱します。

・要件定義書
　　何を作るのかを明文化した、顧客との契約の基礎。

・基本設計書（外部設計）
　　ユーザーから見える部分（画面、帳票、操作感）の定義。

・詳細設計書（内部設計）
　　プログラムの具体的な構造や、クラス図、シーケンス図など。

・DB定義書（ER図）
　　データの繋がりを定義した、システムの「記憶」の設計図。

・API仕様書
　　システム同士がどう会話するかを定めた「共通言語」の辞書。

2. 現場の秩序を守る「ルール・管理系」

　チームメンバーが迷わず動くための「掟」です。

・コーディング規約
　　コードの書き方のルール。読みやすさと保守性を保つ。

・環境構築手順書
　　開発環境を再現するためのレシピ。新メンバー合流時に必須。

・WBS（作業分解構成図）
　　誰が、いつまでに、何をやるかのロードマップ。

・課題管理表（Issue/Backlog）
　　今起きている問題や、やるべきことのリスト。

3. 品質を証明する「テスト・品質管理系」

　作ったものが正しく動くことを保証するためのエビデンスです。

・テスト計画書
　　どのような方針で、何をどこまでテストするかの戦略。

・テスト仕様書（テストケース）
　　「Aボタンを押したらBになる」といった具体的な検証項目。

・テスト結果報告書
　　テストの結果と、発見されたバグの改修状況の記録。

・証跡（エビデンス）
　　スクリーンショットなど、テストを通った物理的な証拠。

4. 運用と生存のための「保守・運用系」

　リリース後、システムが生き続けるために必要なドキュメントです。

・運用マニュアル
　　日々の起動・停止、バックアップ、監視の方法。

・障害対応マニュアル（ランブック）
　　トラブル発生時にどう動くかの「避難訓練マニュアル」。

・リリース手順書
　　本番環境へプログラムを反映させるための、一発勝負の台本。

・構成管理図
　　どのサーバーがどこにあり、どう繋がっているかのインフラ地図。

5. 知恵を共有する「ナレッジ・コミュニケーション系」

　組織の「記憶」を蓄積し、同じ失敗を繰り返さないためのものです。

・Wiki / Notion
　　現場独自のTipsや、よくある質問（FAQ）の集積地。

・議事録
　　「言った言わない」を防ぐための、意思決定の記録。

・振り返り（ポストモータム）
　　プロジェクト終了後や障害後に、何が良くて何が悪かったかを分析した記録。

まとめ：ドキュメントの「鮮度」

　IT現場の生態系において、「古いドキュメントは嘘をつく」と言われます。
　書くことと同じくらい、現状に合わせて「更新し続けること（メンテナンス）」が、この生態系を健全に保つ鍵となります。

【関連記事】

☆IT現場の生態系

☆プロマネの生きる道

☆プロジェクトマネジメントの小径

書籍の紹介

・技術者のためのテクニカルライティング入門講座 第2版 Kindle版
　髙橋 慈子 (著)
　翔泳社; 第1版 (2024/12/18)
　情報をわかりやすく伝えるために必要なのは、センスではなく技術！
　生産性が向上し、相手に伝わる論理的な技術文書の書き方
　日本では、「文章は論理的かつ簡潔に記述する」というテクニックを学ぶ機会があまりありません。
　そこで本書では、忙しい技術者の方でも「テクニカルライティング」を通じて、相手に伝わる技術文書を効率よく書けるようになるテクニックを多数紹介していきます。
　ユーザーマニュアルや障害報告書、提案書といった実務直結の例を多数紹介しているため、すぐに業務に役立てられます。
（ ※ 書籍の解説等は原則としてリンク先（Amazon）における解説をベースに記載しています。詳細内容はリンク先を参照願います。）

*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-

・プロジェクトマネジメント知識体系ガイド
　（PMBOKガイド）第7版 Kindle版
　＋プロジェクトマネジメント標準: PMI日本支部 監訳
　プロジェクトマネジメント協会（PMI） (著)
　一般社団法人 PMI日本支部 (2023/1/6)
（ ※ 書籍の解説等は原則としてリンク先（Amazon）における解説をベースに記載しています。詳細内容はリンク先を参照願います。）

*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-

・図解即戦力　PMBOK第7版の知識と手法がこれ1冊でしっかりわかる教科書 Kindle版
　前⽥ 和哉 (著)
　 技術評論社 (2024/9/20)
　プロジェクトマネジメントの世界標準として知られるPMBOK Guide 第7版の解説書です。「プロジェクトの基本」「価値実現システム」「12の原理・原則」などプロジェクトマネジメントの基礎となる知識のほか、PMBOK第7版のメインテーマともいえる「8つのパフォーマンス領域」について、要点をくわしく解説します。プロジェクトマネジメントの勉強のほか、PMP試験対策の第一歩としてもおすすめできる1冊です。
（ ※ 書籍の解説等は原則としてリンク先（Amazon）における解説をベースに記載しています。詳細内容はリンク先を参照願います。）

*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-

・図解入門よくわかる 最新PMBOK第6版の基本 Kindle版
　鈴木安而 (著)
　‎ 秀和システム (2018/3/23)
　PMBOKガイドは、米国プロジェクトマネジメント協会により、日本語を含め世界11ヶ国語に翻訳・出版されています。翻訳されても、専門用語が多い、カタカナ用語が多いなどの理由からなかなか理解が困難です。本書は、『PIMBOKガイド第6版』の翻訳・監訳チーム・リーダーでもある著者が、本来の意味をなるべくかみ砕いて解説します。イメージしやすいよう図版を豊富に使っているので、初心者からベテランまでわかりやすくなっています。
（ ※ 書籍の解説等は原則としてリンク先（Amazon）における解説をベースに記載しています。詳細内容はリンク先を参照願います。）

*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-

・プロジェクトマネジメントの基本がこれ1冊でしっかり身につく本 Kindle版
　前田和哉【著】
　技術評論社（2022/06）
　本書は、プロジェクトマネジメントについて基本から学ぶことのできる入門書です。プロジェクトマネジメントの基礎知識について解説した後、プロジェクトを「立ち上げ」「計画」「実行」「監視・コントロール」「完了」という5つの段階に分け、各段階において実施すべきこと、注意すべきポイントについて丁寧に解説しています。
（ ※ 書籍の解説等は原則としてリンク先（Amazon）における解説をベースに記載しています。詳細内容はリンク先を参照願います。）

*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-