システムエンジニアの部屋コミュの仕様書の書き方

皆さんの中で、詳細設計書や単体試験仕様書とか
結合試験仕様書とかを書かれている方がいらっしゃるかと
思いますが、効率良く、上手い仕様書の書き方というのは
あるんでしょうか？
経験も比較的浅いというのもありますが、どうにか
上手く作れるようになりたいのです。

こんな本を読むべし！
こんな視点から書くとよい　

みたいなアドバイスがあれば教えてください。

コメント(30)

最初
全て
最新の40件

[1] mixiユーザー 01月14日 21:33

うまいと思う既存の設計書を社内で探すほうが早いかもしれませんね。

会社さん（またはプロジェクトとか）によって、設計書の精度ってゆうか、記述範囲や内容は異なると思うので、一概にはこれがうまい書き方だ！とは説明しにくいかもしれません。
そんな魔法みたいな説明があるのなら、きっと既に有名になっていることでしょう。たぶん。。。

今一番のおすすめは、自社にある設計書だと思いますよ。
一番簡単に入手できるはずで、実際に動いているシステムを見ながら確認することもできるはずなので。

その設計書等を一つずつ解析し、自分なりに読みにくい、わかりにくい、と思うところを改善していくのが、うまい設計書を書けるようになる早道のような気がします。

もっとも、他所の会社さんに行くと通じない文化だったりすることもあるので、注意が必要だとは思いますけれど。

って、こんな回答でいいのか？！

[3] mixiユーザー 01月14日 22:20

>らきさん

同感です。
私も他社で通じない文化で仕様書を書いてるかも。。

まぁ。そんな限られた経験をもとに意見を述べますと。。

大抵の場合、仕様書がカバーしなければならない範囲は膨大で。
全部は書けないし、
気合いで書いても読めないし、
根性で読めても、読んだ後に役にたたない。

なので。。
良い仕様書を書くためのコツは。。

システムの大事なところを書くことではないでしょうか？
システムの大事なところを書けば、
ボリュームが絞れるので
書けるし、読めるし、役に立つ。かと。。

あんま自信はありませんけど。

[4] mixiユーザー 01月14日 22:56

＞raさん

同じくです_no

でも、どこ行っても通用する設計書を書けるＳＥさんなんて、きっとそんなにいらっしゃいませんよねｗ

俺はたまたま、某国産大手メーカーさん、ＳＩｅｒさん、某外資メーカーさんとやりとりがあったので、各社さんの設計書や、設計標準なんかに目を通してきていて、”違う”ということを知っていますが、概ねどこのＳＥさんも、自社の標準でしかしゃべってくれませんｗ

あ、トピずれしたか。。。_no

[8] mixiユーザー 01月15日 11:49

書式とかの話に始終してしまっているようで残念です。
どの段階の仕様書でも

・要求事項（目的）
・概要
・対象範囲
・前提条件
・詳細
・例外時の対応
・注意事項

等を漏らさず、関係者がわかるようなカタチで
書けば、いわゆる「仕様漏れ」は発生しないと思います。
ISO9000sやPMBOK等を参考にされるといいと思います。

[9] mixiユーザー 01月15日 16:50

ＳＥ新人の山裕です。
参考になりますねぇ。
ＳＥって大変そうだなぁ。

[10] mixiユーザー 01月15日 21:08

色々読ませて頂きました。
なるほど～ってな感じです。

私は標準化については、日本ユニシスのＬＵＣＩＮＡ
を使用しています。
（ライセンスの問題がありますが・・・）

納品するお客様に購入していただいてます。

http://www.unisys.co.jp/lucina/tech/

これにより、標準化を決める必要が無くなりました。
書き言葉って人それぞれなので、難しいですね。

[11] mixiユーザー 01月15日 23:12

みなさんこの業界ながいんですか？
自分は来春から皆さんと同業者になります。

仕様書ってちょっと想像しづらいですねぇ。

[12] mixiユーザー 01月15日 23:18

仕様書を作るより、その前が大変です。
一般企業で一人でやってますが、周りの人は開発スキルゼロです。
今日も単なる打ち合わせ程度の内容をデータベースのテーブルに収めるまて詳細を詰めますが。相手は人間レベルでちゃんと説明しているつもりです。
簡単にできないのか、と言われたりします。
まさか、できないのはあなたたちのせい、とも言えないし。
そのうち、言うかもしれませんが。

いかに、曖昧、場当たり、口頭、メモ書きを仕様としてシステムを作る情報として記載するかが今の私にはかなり困難です。
むかつくことを我慢していくのが仕事みたいになってます。

[14] mixiユーザー 01月17日 15:23

書き込みありがとうございます。
思い切って質問して良かったです。

皆さんの書き込み、参考にさせて頂きます。

[15] mixiユーザー 01月23日 00:21

本気に考えるならば、まずシステムのライフサイクルとシステム開発の流れを理解しなければいけません。

と言うのも定義書（設計書）は自分の考えや知識を明示化した資料であって、その文書化されるまでの過程自体が定義作業を行う上で重要な事柄だからです。

逆にいえば、その過程（工程）を理解していれば「受持つ工程で何を解決しなければいけいないのか」が解り、そして「自分を含め周囲に何を伝えなければ行けないのか」が解り、そして結果必要な資料が自ずと解ります。

これを怠ると、定義書テンプレートの空いた枠を埋める為の行為に翻弄され、枠を埋める事が仕事になりますのでご注意下さい。

とは言えども、現実的にはちょっと難しいでしょうから。
皆さんの仰る通り極力多くの定義書に目を通し各工程で記述する事。前後工程の定義書を見比べて発生や加工されている事柄などを整理する事をお勧めします。

また、最近では設計書関連の本も沢山出ていますから、その気になった場合は、色々と本を読み実践してみて下さい。

設計行為自体は非常に難しい事ですから、答えを焦らずに数年間位をかけるつもりで．．．

[16] mixiユーザー 01月23日 02:05

参考になるでしょうか？
私は初めて設計書や仕様書を作り始めた時、実業務の中で、
短期間で設計書・仕様書の作成能力を向上させたいと想い、
以下のようにしました。

-------------------------------------------------
==============================
★ポイント：日頃の努力＆人まね★
==============================

■他人が書いた、【上手い】と思う仕様書を真似る。
　※関数仕様なら、Helpでもよい。

■日頃から、【人から質問を受けない】メールや文章を
　書くよう心がける。

■仕様書／設計書を、年の離れた上司や、若い後輩に見せ、
　感想を【フィードバック】してもらう。

■自分が仕様書や設計書を作成する時、
　【他人が書いた不親切な仕様書や設計書】を思い出す。
-------------------------------------------------

以上です。

業務の都合上、いきなり
『君、今日から設計してね。』
『○○定義書や××規定書作っといて。』
てな事は、よくあります。

私は、非常に実業務で苦労しました。
制御系という環境も少しは関係したかな（笑）

本などで知識（理論）を吸収し、人まねでもなんでも
いいから、日頃から意識してアウトプットする事が
一番いいんじゃないかな？と思います。

[17] mixiユーザー 01月23日 16:40

私は、だめな設計やです。参考にしないでください。
仕様書は、メモ書き。
細部は、口頭のみ。

[18] mixiユーザー 01月23日 19:53

はじめましてです。

えと、仕様書のスキルは、国語力と、有効な記述の能力にわかれます。

国語力は…勉強してください。
有効な記述は、その仕様書の目的と対象読者を明確にしないとできません。

最初のうちはフォーマルな書き方を守ればいいですが、それではいずれ限界がきます。
文書の目的を明確にする訓練をして下さい。

[19] mixiユーザー 01月23日 20:43

　最近、テストファーストとかテストドライブとか言われる手法の影響ですが、仕様＝テスト事項なんだと思いました。それで、「要望→仕様→テスト項目」とたどることができる情報管理システムを作ろうかと。これの要望事項だけを抜き出せば「要望仕様書」、仕様部分だけを抜き出せば「システム仕様書」、テスト項目だけ抜き出せば「テスト仕様書」となる予定です。（予定は未定）

　問題は、「変化の内包」で、要望は常に変化します。それを仕様、テスト項目へと、どう対応づけるか／対応を保ったまま要望の変化をどう記録するか。最近とみに、ウォーターフォールじゃちょっとしたことで「仕様書改訂」に戻らねばならず、逆に「今の仕様内で収める」ことが足かせになっているかな、と思うので。

[21] mixiユーザー 01月25日 22:21

> だんごねこさん

　使ったことないので不明。

　ただ、Ratinalのツールは、Rationalの他のツールと密接に絡んでいるじゃないですか。たとえば、ClearCaseと連携して、ソースコードの復元までやってくれると思います。そこまではしんどい。
　たとえばMSは、今度のVSTSで、そういうことをやります。Borlandからもでています。でも、私が今いるところは、個人の机にはWindows、でも仕事は組み込みUnixなんですね。なので、Rational以外は使い勝手が悪い。そしてRationalは高い。
　逆に連携しないことで、開発環境にも依存しないような。またはClearCaseもVSSも、コマンドラインから構成情報の取得はできるので、自前のデータベースに蓄え直すことで、どの構成管理とも連携できる…かもしれない。

時間くれぇ～（笑） (--;

[22] mixiユーザー 01月27日 23:51

皆さんの書き込みじっくり読ませて頂いてます。

今日もレビューして貰って少々凹みましたが、
ここの書き込みをまた見て「まだ理解が足りてないなぁ」
と反省。

頑張ります。

[26] mixiユーザー 03月21日 23:06

プロセス標準化をするちゅう観点で進めた方が良いですよ、何々のプロセスを実施する過程で「テスト仕様書」「障害報告書」「～」が結果として作成される、みたいな。てか、PMの仕事。

[30] mixiユーザー 03月22日 18:28

自分がドキュメント作る上で気をつけていることは以下ですかね。

・何のためのドキュメントなのかを理解する。(これが最重要)
・できるだけ記号化(式、図、表)する。
・同じことを2箇所以上に書かない。(書いてもいいけどメンテが大変)
・文章は短く、簡潔に。
・2つ以上の意味に受け取れる文章を書かない。
・条件のAND、ORを必ず書く。
・条件を満たす場合、満たさない場合の両方を書く。(「満たさない場合」は意外とみんな忘れがち)
・仕様に対して理由を持たせる。(数年後に理解不能な仕様にならないように)
・必要なことは1から10まで全部書く。(口頭説明をしないつもりで書く)
・必要なこと以外は一切書かない。

ドキュメント自体の目的は、仕様検討や設計作業などの結果を記録することだと思ってます。
皆さんが仰ってるように、大事なのはその過程なので、
ドキュメントを作ること自体を目的にしないことが大切かと思います。

ログインすると、残り12件のコメントが見れるよ