長期のシステム開発、保守におけるドキュメント（仕様書）管理について

Question

今自分が携わってる案件(初期開発は終わって7年ほど保守されてる段階)の話なのですが、
Redmine上に都度都度改修依頼(小さなものだとSlackで)や改修内容の詳細を記したExcelファイル等はあるのですが、
仕様について一括で管理されているドキュメントというものが存在せず、今動いてるものが仕様書という感じです。

この案件にアサインされていてよくあるのが、既に退社した人が開発した機能や複雑度の高い機能については
上流から下流にいる人間誰1人把握していない場合も多く、

上流の人『これバグっぽくない？』→RedmineやSlack、コミットログを1時間ほど漁る→『あ、これ仕様です。』
というような全く生産性のない作業や、

上流の人『ここの仕様どうなってるの？』→誰も答えられない→『調査だけでn日かかります。』
といったことが結構あります。

今いるメンバーの知識に依存して業務が回っている面が多いので、
特に困るのが今アサインされてるメンバーが退社して入れ替わりが発生したり
新入社員が新たにアサインされたときで、『引き継ぎ』だけで結構な日数がかかってしまいます。

この手の仕様を把握できてない故に発生する作業や課題に直面する度
「ドキュメントがもうちょっとまともに管理されてたらなぁ」と思ってしまいます。。。

勿論運用される年数や規模にもよるとは思うのですが、システム開発における
システムの仕様等を記したドキュメントってどういう形でどこまで管理されるべきなのでしょうか？
漠然とした質問ですいません・・・

Answer 1

直接の回答ではありません。

わたしはDBのパフォーマンス・チューニングで呼ばれることが多いです。
長期間運用されてるシステムであろうとまだカットオーバーされて間もないシステムであろうと、テーブル定義書さえ最新の状態で維持されているシステムは少ないです。
ドキュメントがまともでないシステムほど問題が多いのは共通しています。涙

ドキュメントをきちんと管理するにはそれなりに時間も費用もかかります。
どれだけまともにシステムを維持しようとしているかという会社の姿勢も大きいです。
人材の入れ替わりも多いところはなぜこんな設計にしたのかだれもわからない状況だったり。
辛い過去がよみがえることの多い今日この頃。

Answer 2

私も直接の回答ではないのですが、SIerとしての経験上の話をします。

SIerにとってドキュメントとは、お客様のためのものであって自分たちのためのものではない、という意識があるように思えます。
ほとんどの契約においては初期納品物にドキュメントが含まれていて、また、ドキュメントの厚さで成果物の価値を判断するお客様が少なからずいるので、最初は(少なくとも見てくれだけでも)きちんと作成すると思います。
ただ一度運用フェーズに入ってしまうと、ドキュメント更新に工数を割かず担当者レベルで作成した記述粒度もレベル感もまちまちなドキュメントだけが作られていくという状況を多く見てきました。

一方で運用開始後もきちんと仕様書を維持管理しているプロジェクトも見てきましたが、そのようなプロジェクトには以下の傾向があるように思えます。

・お客様サイドが技術的に詳しく、きちんと内容を読み込んでいる。
・なのでプロダクトやサービスに変更等が生じた際は、改訂仕様書の納品を契約上の義務としてSIerに課している。
・読まれること、利用されることが想定されているので、記載内容が分かりやすい。
・運用開始後の修正・機能追加に伴うドキュメント作成の工数を費用化している。
・機能追加や修正について、SIerに納得感がある。(内容や費用において)

SIerの立場として、ITのプロではないユーザを軽々に自分目線で批判するのは慎まなくてはいけないとは思いますが、お客様が自分の利用するIT技術・サービスに主体的に関わり、SIベンダをきちんとコントロールし、適正な対価を支払うと言うことがもう少し浸透すれば、おのずとドキュメントの維持管理もきちんとしてくるのではないかと感じています。

Answer 3

ドキュメントってどういう形でどこまで管理されるべきなのでしょうか？

難しい質問ですが、重要な問題ですね。
質問文が「べき」なので、理想論だけ言いますね。

まず一方の極は、「ソースコードが仕様書」だとしてドキュメントを作らない立場で、
もう一方の極は、「ソースコードと一対一対応する詳細設計書」を作る立場です。

しかし、私が理想と考える立場は、その中間の「必要十分なドキュメントを作成する」です。
じゃあ、その「必要十分」な量はいくらかが、次の課題になってきますよね。

「必要十分」というのは、「システムの全期間で総コストが最小」になる量と考えます。

解説すると、この「コスト」というのは、ドキュメントを作るコストと、
ドキュメントを作らないことで発生する、コードを読むコストの両方です。

また「全期間」がポイントで、書き捨てのワンライナーにドキュメントは作りませんし、
逆に何十年も保守する前提の大規模システムなら、ドキュメントなしはありえません。

後はコストを実測して（これが難しいが）、ドキュメントの量を最適化していきます。

ただまあ、たとえば金融系は監査が厳しいので、減らせない業界もあるでしょうし、
受託だと詳細設計書を要求される、とか商慣習の都合が現実的にはあるでしょうが。

---

量だけでなく質についても触れます。何を書くかの問題です。
そこでまず、テストにはドキュメントの側面があることを指摘したいです。

「ソースコードが仕様書」だと、ある挙動が仕様かバグかどうか、
後から入って来た人間が判定不能になる問題があります。
しかし、「テストが仕様書」なら、コードと分離されています。

質問タグに「アジャイル」がついてますので触れますと、
アジャイルでは「完全なドキュメントより動くソフト」を重視しますが、
その代わりテストを書く発想があります。

テストがドキュメントの代替なので、
たんに面倒だから両方なし、では上手くいきません。
また、リファクタリングで、ソース自体の可読性も上げます。

---

もし、組織の制約がなくて、自分だけで開発も保守もするとしたら、
自分なら何が欲しくて、何を残したいか、と考えると議論しやすいです。

私なら、明確な要件定義、テスト、リファクタリング、コメント、UML、
バージョン履歴や自動化タスク、障害対応など重要な局面の文書だとか、
個々は完全でなくても、全体のバランスを考えて、労力を割り振りますね。

Answer 4

べき、という話であれば、ある程度の技術力をもった技術者がドキュメントを確認するだけで仕様を理解でき改修を行えるようなものであるべきだと思います。
でも現実は残酷です。そんなものは少数派です。

でもだからこそGithubのようなサービスが生まれてより簡単に管理できるようになってきているのだと思います。
とは言っても、技術者の情報を後に残そうという姿勢がドキュメント管理には一番の特効薬だったりします。

Answer 5

調べればわかるのであれば、取り敢えず問題ないかなとも思います。

特に、仕様が複雑な点は、情報量が多くきちんと仕様を残すのは現実的で無いことが多いです。
しかしながら、該当箇所の変更履歴からメンテの内容に関する資料がヒモついていることが大事だと思います。

該当する箇所がわからないという点についてはむしろ設計が出来ていないのが問題かなと思いますし、分からないと思った瞬間が資料の作り時です。比較的資料がしっかりしているシステムを担当したことがありますが、大抵のメンバーは仕様書を確認せずソースコードを当たっていました。にも関わらず仕様書のメンテは義務化されていました。

なぜ、仕様書を読まないかというと、３つほど理由があるからです。
１．仕様書が間違っている。これはいけないことですが、完全にすることは出来ません。
２．ソースコードは間違っていない。ただし、そうなっている経緯などが解りません。
３．調べたいことが仕様書に書いていない。いくら細かく書いていても経緯や設計方針などは書かないことが多く、結局ベテラン任せになってしまいます。

結局調べる人目線の資料が揃っていることはほとんど無いため、どちらかと言うと必要になってから作り、作ったからには使いやすいようにメンテし続ける事が大事という結論になりました。（もちろん、使わない仕様書は破棄していくということも平行する必要があります。）