質問: 今自分が携わってる案件(初期開発は終わって7年ほど保守されてる段階)の話なのですが、 Redmine上に都度都度改修依頼(小さなものだとSlackで)や改修内容の詳細を記したExcelファイル等はあるのですが、 仕様について一括で管理されているドキュメントというものが存在せず、今動いてるものが仕様書という感じです。 この案件にアサインされていてよくあるのが、既に退社した人が開発した機能や複雑度の高い機能については 上流から下流にいる人間誰1人把握していない場合も多く、 上流の人『これバグっぽくない?』→RedmineやSlack、コミットログを1時間ほど漁る→『あ、これ仕様です。』 というような全く生産性のない作業や、 上流の人『ここの仕様どうなってるの?』→誰も答えられない→『調査だけでn日かかります。』 といったことが結構あります。 今いるメンバーの知識に依存して業務が回っている面が多いので、 特に困るのが今アサインされてるメンバーが退社して入れ替わりが発生したり 新入社員が新たにアサインされたときで、『引き継ぎ』だけで結構な日数がかかってしまいます。 この手の仕様を把握できてない故に発生する作業や課題に直面する度 「ドキュメントがもうちょっとまともに管理されてたらなぁ」と思ってしまいます。。。 勿論運用される年数や規模にもよるとは思うのですが、システム開発における システムの仕様等を記したドキュメントってどういう形でどこまで管理されるべきなのでしょうか? 漠然とした質問ですいません・・・
回答: > > ドキュメントってどういう形でどこまで管理されるべきなのでしょうか? > > > 難しい質問ですが、重要な問題ですね。 質問文が「べき」なので、理想論だけ言いますね。 まず一方の極は、「**ソースコードが仕様書**」だとしてドキュメントを作らない立場で、 もう一方の極は、「**ソースコードと一対一対応する詳細設計書**」を作る立場です。 しかし、私が理想と考える立場は、その中間の「**必要十分なドキュメントを作成する**」です。 じゃあ、その「**必要十分**」な量はいくらかが、次の課題になってきますよね。 「必要十分」というのは、「**システムの全期間で総コストが最小**」になる量と考えます。 解説すると、この「コスト」というのは、ドキュメントを作るコストと、 ドキュメントを作らないことで発生する、コードを読むコストの両方です。 また「全期間」がポイントで、書き捨てのワンライナーにドキュメントは作りませんし、 逆に何十年も保守する前提の大規模システムなら、ドキュメントなしはありえません。 後はコストを実測して(これが難しいが)、ドキュメントの量を最適化していきます。 ただまあ、たとえば金融系は監査が厳しいので、減らせない業界もあるでしょうし、 受託だと詳細設計書を要求される、とか商慣習の都合が現実的にはあるでしょうが。 量だけでなく質についても触れます。何を書くかの問題です。 そこでまず、テストにはドキュメントの側面があることを指摘したいです。 「ソースコードが仕様書」だと、**ある挙動が仕様かバグかどうか**、 後から入って来た人間が判定不能になる問題があります。 しかし、「**テストが仕様書**」なら、コードと分離されています。 質問タグに「アジャイル」がついてますので触れますと、 アジャイルでは「完全なドキュメントより動くソフト」を重視しますが、 その代わり**テストを書く**発想があります。 テストがドキュメントの代替なので、 たんに面倒だから両方なし、では上手くいきません。 また、**リファクタリング**で、ソース自体の可読性も上げます。 もし、組織の制約がなくて、自分だけで開発も保守もするとしたら、 自分なら**何が欲しくて、何を残したいか**、と考えると議論しやすいです。 私なら、明確な要件定義、テスト、リファクタリング、コメント、UML、 バージョン履歴や自動化タスク、障害対応など重要な局面の文書だとか、 個々は完全でなくても、全体のバランスを考えて、労力を割り振りますね。