まとめ
開発ドキュメントを、リリース前だけ必要なものと、リリース後も必要なものを、ディレクトリでわけて整理するとスッキリする。
開発ドキュメントの整理方法
リリース後もみるドキュメントのみ残して、それ以外は削除するなり、アーカイブするなりします。
ただし、要件定義書/内部設計書（の一部）/テスト仕様書などリリース後は見ないであろうドキュメントたちも、リリースするまでは必要です。
なので、それらは開発中はリリース後も必要なドキュメントも含めて、すべて現在進行中ディレクトリ（ongoing)などの中にいれます。
リリースされたら、要らないものは削除かアーカイブ、要るものは別のディレクトリに移動します。
これでスッキリするはず...！
背景
現在お世話になっているチームでは、"Ongoing"というディレクトリに現在進行中のプロジェクトのドキュメントをまとめています。
それをみて、開発ドキュメントも、プロジェクトが進行中の間だけ参照するドキュメントと、リリース後も参照するドキュメントを、ディレクトリを分けるようにすれば、必要な情報に辿り着きやすくなるのではないかと思い整理してみました。
現場によってはドキュメント一切なしで、issueのみで進めてるところもあるそうです（すごい...）。それで問題なければ、それでいいと思います。（むしろ理想...）
一方で、開発ドキュメントがありすぎると、システムを理解するために必要な情報が埋もれてしまいます。
新しく入った現場でドキュメントの量に圧倒された経験はありませんか？
・何から見ればいいのかわからない。
・ドキュメントがメンテされておらず、最新の情報と古い情報が混在している。
・質問をしたら、ここに書いてあるよ、とそっけなく言われる。辛い。
新規参画メンバーにこのような辛い思いをさせないようするためには、必要な情報のみに絞ることが重要と思います。
ここでは、多すぎるドキュメントをどのように整理すれば、はじめて参画する人もスムーズにシステムを理解できるかを考えたいです。自分はアプリエンジニア（とくにアプリとWEB）ですので、その観点でのみ記載していることをご留意ください。
リリース後もみるドキュメントは何か？
システムを理解するために見たい情報は、リリースされているプロダクトの全体像くらいです。あとは、開発環境を構築して試しに動かすことができれば、なんとなくは理解できると思います。
はじめて参画する人向けドキュメント
開発ドキュメントとしては、以下があればいいと思います。
- 開発環境構築手順
- システム構成図
仕様確認用のドキュメント
すでに参画している人が仕様を思い出すためにも、以下の開発ドキュメントは役立ちます。
- 外部設計書
- ER図
- 画面設計書
- 内部設計書
- シーケンス図
- アクティビティー図
そのほかにもあると思いますが、あくまで例になりますので...重要なのは、リリース後も見るのか？という観点で分類することです。
ここでは以下を除外しました。
| ドキュメント | 例 | 説明 |
|---|---|---|
| 開発前に作成するドキュメント | 要件定義書 | 開発者はそもそもあまり見ない（？）し、リリース後は責任回避（or 追求）のためにしか見ない |
| 内部設計書（一部） | クラス図 | 基本的にはコードを見ればわかる内容のため。特に、クラス名などコードに依存する記載があるもの（メンテも大変 ） |
| テスト仕様書 | 結合テスト仕様書, シナリオテスト仕様書 | 実施済みのテスト仕様書は、外部設計書に記載してある内容のエビデンスでしかないため |
開発チームがリリース後もみる・みないという観点で開発ドキュメントを整理する方法をご紹介しました。
ありがとうございました。
参考