ドキュメントの書き方指南書を探しています。

質問

普段PGをやっています。
最近何かと詳細設計書や画面遷移図を書いてくれと頼まれることが多くなってきているのですが、自分にはあまり経験がありません。

ほとんど、プログラムができてから詳細設計書という流れなので、自分がかかわったことがないのです。

後学のためにも、ちゃんと覚えたいと思い、サイトや本を探してみたのですが、一般的なフォーマットになるものは見つかりませんでした。

ITMediaとかも見たんですが、逆に詳しすぎて、簡易的な画面遷移図・詳細設計などには向きませんでした。

どなたかドキュメントの書き方が具体的にわかるような本をご存知ないでしょうか？

よろしくお願いします。

回答No.1

anmochi · ベストアンサー

答えを書くことは残念ながら私にはできないので、逆の立場で解説する事で回答とさせていただく。

・どこにもドキュメントの記述法やレイアウト・サンプルが転がってないのはどうしてだ！
→それこそがソフトハウス各社の社外秘ノウハウだからです。

　まず、創世記の各社はそれぞれ独自にフォーマットを作成してきた。みんな自分たちで決めた訳だ。社外秘ノウハウというほど大げさなものではないのだけど、結局あなたの会社にあった書き方はよその会社の人には解説できないのですよね。
　「うちの会社ではこうやってるけど」っていうのであれば言うことはできると思うんだけど、まぁあんまりそういう事はしないね。不文律なのか何なのかは私も知らないのだが。

と、これだけでも何なので、気をつけてほしい点をいくつか上げてみようか。
・オレフォーマットを作ってみる。
　会社とは別に（いや、会社のをある程度は流用してもよいと思うけど）、自分が詳細設計者、プログラム設計者だったら、開発を担当する人に何を伝えたいか、何を伝えなきゃ彼らは作れないか、という事を考えるために、人のフォーマットじゃなく、自分で全てを一度練り上げてもらいたい。この作業が、プログラマが年数を重ねたとき、デキル設計者になれるかどうかを決めると言っても過言ではない。
・設計書は手段である（設計書はプラットフォームによって変わる）。
　COBOLとサーバーサイドJavaで同じフォーマット使ってる会社があったらきっと空中分解か大喧嘩ですよ。
　綺麗な体裁ではなく、項目に着目して欲しい。設計書の各シートに書かれてある項目は、必要があったから項目として挙げられている訳で、レイアウトありき、書き方ありきが立脚点だと大事な事が見えない設計者に成り下がってしまう。驚くか「ああ、そうだよね」と思うかはわからないが、体裁ばかりこだわって肝心の中身がない設計書を書く人が（最大手の人でも）なんと多い事か。
　体裁がめちゃくちゃ綺麗で何を書いてるのかさっぱりわからないものよりも、実装して欲しい機能がきちゃない字でされど過不足なく箇条書きされているメモ紙の方が100倍マシなのです。

　よいですね。書き方ももちろん大事なのですが、本質は書いているオレは読むアイツに何を伝えたいのか、という最も初歩的な話なのです。そういう観点で自分で考えてみるのはすごく勉強になると思いますぜ。

お礼

うすうす気づいてはいましたが、やっぱりフォーマットは各自でって感じなんですね。。。

丁寧な解説ありがとうございます。すごく納得しました。
いきなり何が変わるわけじゃないですが、念頭において書いてみます。
ありがとうございました。

回答No.2

junkUser

UMLがあります。
お客さんとの交渉や、外注する際にも利用できるので勉強しても無駄にはならないと思います。

http://www.atmarkit.co.jp/fjava/devs/01fivemin/fivemin00.html

お礼

確かにUMLはよく使いますね。

ありがとうございます。