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

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

新規登録して質問してみよう
ただいま回答率
85.50%
UML

UML(統一モデリング言語)は、主にオブジェクト指向分析や設計を目的に記法の統一が図られたモデリング言語です。要求分析・システム分析・設計・テストなど幅広いシステム開発のフェーズを網羅しています。

Java

Javaは、1995年にサン・マイクロシステムズが開発したプログラミング言語です。表記法はC言語に似ていますが、既存のプログラミング言語の短所を踏まえていちから設計されており、最初からオブジェクト指向性を備えてデザインされています。セキュリティ面が強力であることや、ネットワーク環境での利用に向いていることが特徴です。Javaで作られたソフトウェアは基本的にいかなるプラットフォームでも作動します。

PHP

PHPは、Webサイト構築に特化して開発されたプログラミング言語です。大きな特徴のひとつは、HTMLに直接プログラムを埋め込むことができるという点です。PHPを用いることで、HTMLを動的コンテンツとして出力できます。HTMLがそのままブラウザに表示されるのに対し、PHPプログラムはサーバ側で実行された結果がブラウザに表示されるため、PHPスクリプトは「サーバサイドスクリプト」と呼ばれています。

アジャイル

アジャイルは、 迅速かつ適応的に対応できるように、効率的なシステム開発 を行うための開発手法群の総称のことです。

Q&A

解決済

5回答

3061閲覧

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

opoonabst

総合スコア264

UML

UML(統一モデリング言語)は、主にオブジェクト指向分析や設計を目的に記法の統一が図られたモデリング言語です。要求分析・システム分析・設計・テストなど幅広いシステム開発のフェーズを網羅しています。

Java

Javaは、1995年にサン・マイクロシステムズが開発したプログラミング言語です。表記法はC言語に似ていますが、既存のプログラミング言語の短所を踏まえていちから設計されており、最初からオブジェクト指向性を備えてデザインされています。セキュリティ面が強力であることや、ネットワーク環境での利用に向いていることが特徴です。Javaで作られたソフトウェアは基本的にいかなるプラットフォームでも作動します。

PHP

PHPは、Webサイト構築に特化して開発されたプログラミング言語です。大きな特徴のひとつは、HTMLに直接プログラムを埋め込むことができるという点です。PHPを用いることで、HTMLを動的コンテンツとして出力できます。HTMLがそのままブラウザに表示されるのに対し、PHPプログラムはサーバ側で実行された結果がブラウザに表示されるため、PHPスクリプトは「サーバサイドスクリプト」と呼ばれています。

アジャイル

アジャイルは、 迅速かつ適応的に対応できるように、効率的なシステム開発 を行うための開発手法群の総称のことです。

1グッド

2クリップ

投稿2016/10/22 09:07

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

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

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

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

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

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

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

LLman👍を押しています

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

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

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

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

guest

回答5

0

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

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

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

投稿2016/10/22 09:31

Orlofsky

総合スコア16415

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

0

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

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

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

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

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

投稿2016/10/22 11:33

ynakano

総合スコア1894

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

0

ベストアンサー

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

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

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

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

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

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

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

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

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


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

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

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

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


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

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

投稿2016/10/22 11:24

LLman

総合スコア5592

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

0

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

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

投稿2016/10/22 10:14

matsu

総合スコア702

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

0

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

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

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

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

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

投稿2016/10/22 10:20

iwamoto_takaaki

総合スコア2883

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

あなたの回答

tips

太字

斜体

打ち消し線

見出し

引用テキストの挿入

コードの挿入

リンクの挿入

リストの挿入

番号リストの挿入

表の挿入

水平線の挿入

プレビュー

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

ただいまの回答率
85.50%

質問をまとめることで
思考を整理して素早く解決

テンプレート機能で
簡単に質問をまとめる

質問する

関連した質問