読者です 読者をやめる 読者になる 読者になる

くんすとの備忘録

プログラミングや環境設定の覚え書き。

システム開発のドキュメントについての考えをざっくりとまとめてみた。

概要

仕様書必要論・仕様書不要論などに違和感があったので。
チキンな上に面倒臭がりで飽き症なので、ざっくりと書きます。

前提

この文章では、詳細レベルで作成される「仕様書」「設計書」「詳細設計書」と呼ばれるものをざっくりまとめて「詳細レベルのドキュメント」もしくは「ドキュメント」と書きます。
(要件確認書や基本設計書みたいなのは別ね)

要件確認書・基本設計書・アーキテクチャの図みたいなやつ、はそもそも必要。
詳細レベルのドキュメントについては検討が必要。

ざくりとした意見

詳細レベルのドキュメントにはざっくりと以下の読み手が想定されます。

1. 一次開発者
2. 承認者(Yes/No を決める人 or お金を出す人)
3. 保守担当(二次開発者)

それぞれに対して別のアプローチが必要だと考えます。

1. 一次開発者 の為のドキュメント

大体必要。いらない時もある。
従来のWF開発のように、設計書を書く人とソースを書く人が別の場合は必要。ただし、相手のレベルやアーキテクチャに合わせたものにするべき。
設計者=ソース書く人で、作っても読まないしメンテもしないよ、っていう場合は不要。確認やメモのために作るのはおこのみで。

2. 承認者(Yes/No を決める人 or お金を出す人)の為のドキュメント

必要。作っていなくて後で後悔することもあるのでは。
1~2枚くらいの紙に、業務視点でわかりやすい図表があればよし。
Yes/No を判断してもらうための資料。開発者目線で書いてはダメ。

3. 保守担当(二次開発者)の為のドキュメント

必要。作っておかないと人(他人 or 未来の自分)に迷惑がかかる。
調査や修正(大体はif文ひとつ突っ込むだけとか)のために使うので、動いているソースに近いものがよい。
むしろソースから自動生成したものでいいと思う。

ざっくりとしたまとめ

詳細レベルのドキュメントについて

1. 一次開発者向け -> WFなら必要。その他ではおこのみで。
2. 承認者(Yes/No を決める人 or お金を出す人)向け -> むしろ別の資料を作りましょう。
3. 保守担当(二次開発者)向け -> 自動生成でもいいよ。メンテしてね。

ちゃんと読み手と使われ方を想定して作らなきゃ無意味。


今はざっくりこんな感じ。
半年後にはまた考えが変わってるかも。


メモ追記

一次開発用のドキュメントに但し書きを書いておいて書き捨てにする、という手。

これは、一次開発でのみ使用するドキュメントです。
プログラム作成後はメンテナンスされません。
最新の仕様については、ソースコードより自動生成されたドキュメント「~~」を確認して下さい。

開発時のバグ修正・保守や二次開発の際は、自動生成されたドキュメントと、そこから起こした修正仕様書をする運用にする、とか。

広告