ドキュメント・ベースは階層構造をもたせる

ドキュメント・ベースには様々な資料が置かれるが、ある程度のカテゴリ分けを決めておかないと、どこに何のファイルを置けばよいのか、どこに何のファイルが存在するのかが分からなくなってしまう。毎度「あのファイルはどこですか？」と聞く無駄な時間が増えたり、有用な資料の存在に気付かず問題解決が遅れたりしかねない。

どんなシステム、プロジェクト、案件でも、大体次のような階層構造をベースに資料を分けておけば、迷いにくい。

プロジェクトルート
├ ドキュメント・ベースの案内
├ 設計
│ ├ システム仕様書 (システムの概要・目的、機能一覧)
│ ├ システム構成図 (サーバ構成・ネットワーク構成)
│ ├ 設計書
│ └ 環境一覧 (接続情報) …など
├ 開発
│ ├ ルール
│ │ ├ コーディングルール
│ │ ├ 開発ツール
│ │ ├ コード・ベースの案内
│ │ └ テスト仕様書フォーマット …など
│ └ 開発案件
│    └ 2020-01 〜〜機能追加
├ 運用
│ ├ ルール
│ │ ├ 緊急対応時のフロー (ルール)
│ │ ├ 運用手順書 (サーバ接続手順、リカバリ手順など)
│ │ └ 障害管理票フォーマット …など
│ └ 過去対応
│    └ 2020-01-01 〜〜障害対応
├ プロジェクト管理
│ ├ マスタスケジュール
│ ├ メンバ管理 (連絡先・スキルマップ)
│ ├ タスク・ベースの案内
│ └ コミュニケーション・ベースの案内 …など
├ 技術情報
│ └ (システムや案件によらない技術ネタ)
├ 議事録
│ ├ 議事録フォーマット
│ └ 2020-01-01 〜〜打合せ
└ その他
   └ (置き場に迷ったもの)

注意点は以下のとおり。

プロジェクトルート直下に置いて良いファイルは ドキュメント・ベースの案内 のみ
- これがいわゆる README の役割を果たすどこに何があるか、という案内であり、どこに何を置くべきか、というルールブックとなる
他ベースへの案内を作る
- よほどレガシーな環境でなければ、Git や Redmine、Slack 等のツールを使っているはずなので、開発/ や プロジェクト管理/ の配下には、そうしたコード・ベース、タスク・ベース、コミュニケーション・ベースへのリンクを設けておく
- 他ベースへのリンクを展開するとともに、コード・ベースであればブランチ戦略、タスク・ベースであれば記載要項などのルールをまとめておくと良い
設計/ 配下の設計書ファイル類の立ち位置
- 現行の本番環境の仕様を確認するためのモノであること
- 開発案件の中で設計書を執筆する際は、このディレクトリ内のファイルを直接更新するのではなく、「開発案件」内にコピーして編集する (Git 管理している場合は master ブランチを直接書き換えない、ということになる)
- 本番リリースされたら、「開発案件」内で加筆修正したファイルを、この「設計」配下にマージする
開発/・運用/ 直下はストック情報とフロー情報で分ける
- 大まかに、ストック情報を格納する「ルール」ディレクトリと、フロー情報を蓄積していく「開発案件」「過去対応」といったディレクトリの2つに分けると良い
- こうすれば、記載要項や雛形は「ルール」ディレクトリを見ればすぐに探せるし、過去の案件の資料は時系列に並ぶので探しやすい
技術情報/ はなくても良い情報だけ書く
- プロジェクトを通じて学んだ技術ネタをまとめる領域だが、プロジェクトに必要な情報を直接書かないよう、周知徹底したい
- 例えば、「開発 DB への接続方法」は 設計/ 配下にまとめておくべき情報だし、「DB のバックアップ方法」は 運用/ 配下に置く運用手順書になるべきである
- 「方法」と書くと技術ノウハウっぽく感じてしまうので、「手順」と言い換えられる場合は手順書にまとめることを検討する
- この 技術情報/ 配下には「稼動中のサーバを一覧表示するワンライナー」や「Excel でコレをやる時の簡単な方法」のように、ブログで一般公開できるような情報に汎用化しておくこと
- 設計資料とまではいかないけど、ノウハウを共有したい、という時の補助的な領域であること
- この配下にカテゴリを作るのであれば、Awesome や cheat.sh の分類を参考にすると良いだろう
その他/ は使わないようにする
- 一時的にファイルを置く場所ではない単純に「一時的に置きたいファイル」は、大概「開発案件」「運用」「議事録」のどこかに置けるはずのモノである
- 原則、その他/ 配下には何も置かないようにするどうしても置き場に迷った場合に使って良いこととする
- 定期的にパトロールし、いつまでもココにファイルが置かれていない状態にする
- ココに置かれるファイルの内容に合わせて、「開発」や「運用」の配下に階層を作ってあげることにする

こうしたドキュメント・ベースのカテゴリ設計思想は、大抵他の人には伝わらない。「思い」は伝わらないモノと諦め、自主的にパトロールして、何度でも同じ注意をして、ルールを徹底させ続けるしかない。