質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

89.07%

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

解決済

回答 5

投稿

  • 評価
  • クリップ 2
  • VIEW 1,867

opoonabst

score 258

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

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

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

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

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

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

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

  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 過去に投稿した質問と同じ内容の質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 5

+3

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

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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

checkベストアンサー

+2

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

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

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

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

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

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

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

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

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


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

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

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

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


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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+2

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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

+2

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

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

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

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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

0

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

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

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

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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 89.07%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

関連した質問

同じタグがついた質問を見る