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

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

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

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

注意点は以下のとおり。

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

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

ついでに、Bash スクリプトでこのようなディレクトリ構造を一括作成できるようにしておくと、何かと便利。

#!/bin/bash

echo 'Start'

mkdir -p \
  '10-要件定義' \
  '20-設計' \
  '20-設計/テンプレート' \
  '20-設計/システム仕様書' \
  '20-設計/システム構成図' \
  '20-設計/ネットワーク設計' \
  '20-設計/インフラ設計' \
  '20-設計/機能一覧' \
  '20-設計/機能定義' \
  '20-設計/CRUD 図' \
  '20-設計/画面一覧' \
  '20-設計/画面設計書' \
  '20-設計/画面遷移図' \
  '20-設計/帳票一覧' \
  '20-設計/帳票設計書' \
  '20-設計/API 一覧' \
  '20-設計/API 設計書' \
  '20-設計/DB 一覧' \
  '20-設計/DB 設計' \
  '20-設計/ER 図' \
  '20-設計/非機能要件' \
  '20-設計/運用設計' \
  '20-設計/環境一覧' \
  '30-開発' \
  '30-開発/開発規約' \
  '30-開発/過去案件' \
  '40-テスト' \
  '40-テスト/テスト計画' \
  '40-テスト/テスト仕様書' \
  '50-運用' \
  '50-運用/運用ルール' \
  '50-運用/過去対応' \
  '60-プロジェクト管理' \
  '60-プロジェクト管理/見積' \
  '60-プロジェクト管理/マスタスケジュール' \
  '60-プロジェクト管理/WBS' \
  '60-プロジェクト管理/メンバ管理' \
  '60-プロジェクト管理/課題' \
  '60-プロジェクト管理/辞書' \
  '70-技術情報' \
  '80-議事録' \
  '80-議事録/テンプレート' \
  '90-受領資料' \
  '99-その他'

touch \
  'プロジェクトベース案内.md'

tree
echo 'Finished'