わかりやすい仕様書の書き方

質問

現在プログラマをしているのですが、
私の会社は自社ソフトウェアを扱う小さな会社という事もあり、
会社では仕様書を一切書かず、わからないことがあれば各担当した
プログラマに聞きにいく、といった感じになっています。
しかし、今回自分が不便を感じた事もあり、自分が作ったものだけでも
文章でまとめて書いておこうと思うのですが、どのように書いていったら良いものなのか書こうとして躓いてしまいました。
あとから見直してわかりやすいような仕様書・・・この場合出来上がったものをまとめるのですが、書き方を教えていただければと思います。
よろしくお願いいたします。

回答No.1

dexi · ベストアンサー

元ＳＥです。
メインの流れは簡単な図と文章でおこし、それぞれの処理には識別できる記号をつけます。処理はそれぞれ使用をまとめます。
後はそれらをきちんと整理しておけば、後でわかりやすいのではないでしょうか。詳しい処理がわかりませんので、これ以上の説明は難しいですが、もっとも大切なのは「決めたフォーマットを今後も守ること」です。
今後、誰が見ても理解できるようにしておくことが理想ですから、仕様書の作成日・作成者はもちろん、修正を加えた人も修正日・修正内容を残せるようにもしておくべきかと。

お礼

大きな流れを書いて、細かい流れを書いていくのですね。
後々の修正の事も考えて書いていくのですね。
回答ありがとうございます。

回答No.4

tkkari

現役SEです。
#2様がおっしゃるように、仕様書にも様々なものがあります。ですので、どのような仕様書をお書きになりたいのかを教えていただけると助かります。

少なくとも、
　・誤解のない言葉で表現すること
　・注意・制限事項は必ず記述すること
　・図によってシステムの流れがわかるようにすること
　・定義は必ず残すこと
は必要でしょうか。

私は、フォーマットはある程度決めた方が良いかと思います。
「自分だけわかる仕様書」をつくるならフォーマットがあってもなくても良いとは思いますが、もし「誰でもわかる仕様書」を作ろうとするならば、フォーマットは決めておくべきだと思います。

＞わからないことがあれば各担当した
＞プログラマに聞きにいく、といった感じになっています

プログラマは、仕様書をもとにプログラムを行うものであると思っています。ですので、プログラマに仕様を聞きにいく、というのは少々違うと思います。まずは、仕様書をしっかりと固める。それに基づいてプログラマに仕様を引き継ぎ製品をつくる、ということが大切ではないでしょうか。
その仕様をしっかりさせるには「仕様書」をきちんと書くことが必要です。

お客様とトラブルが起きる場合、「仕様に対する理解の相違」があります。
仕様書に起こすことで、互いの認識を確認することができます。ですので、ぜひ自分だけでなく社内に仕様書の文化を根付かせていただければと思います。（偉そうなことを申し上げまして申し訳ありません）

お礼

うちの会社では、営業からほしいといわれた機能を作るのに適していると思われる各システム社員が具体的に考えて作る(SE兼PG？)ような感じで作っています。言葉足らずで誤解を招きました。なにぶん、小さな会社で、請け負うのではなく自社ソフトすので、全てを自分で行うのです。出来上がって機能が足りなければ、営業から言われてつけたし、リリースするのですが、とりあえず、リリース状態のものを
後々のためにまとめておきたいと思っています。
全体の流れと、詳しい説明をわかりやすく書いて行きたいと思います。
ありがとうございました

回答No.3

linus1974

言語は何ですか？？？？？？？？？？？？？？？

補足

C++Builder6です

回答No.2

noname#18558

＃１の人とはちょっと違う意見を。
まず、決まったフォーマットは作らないほうがいいと思います。
変に型にはまってしまい、自分の思った表現に合わないことがあります。
そのため、逆に分かりにくいものが出来上がったりしますので、できるだけ自由に書けるものがいいです。
図は大切です。
言葉では表せないようなことが表現できます。
言葉で説明するのが難しいと思ったら図で描いてみましょう。
フローチャート、UML、ER図、マトリックスなど。

あと、仕様書といってもさまざまです。
基本設計書、詳細設計書、コード設計書などあります。
この場合、コード設計書でしょうか？
それぞれに、設計書の粒度が違いますので分別して下さい。

あと、これは最も重要なことですが、わかり易い言葉で書くということです。
誰が見ても同じような理解ができる言葉で書きます。
例えば、「空の文字列」ということは、例えばnullだったり、スペースが入っててもいいのかなど、読み手によって様々に理解が変わりますので、気をつけて下さい。

お礼

とにかくわかりやすく、というのがキーなのですね。
今書こうとしたら、ソースのコメント(ほぼ全行に書いてあるのですが)をつらつらと並べているようになってしまいました＾＾；
図を取り入れてわかりやすくしたいと思います。
ありがとうございました

補足

そうですね、コード設計になると思います。
基本的な使い方として、このボタンを押したらどうなって・・・というのは単純なものですぐ動かせばわかるのでいいのですが、
ボタンを押したらどの関数が呼び出され、どのようなライブラリが使われていて、又、関数内の詳細な動きをまとめておき、今後変更がある場合、バグが見つかった場合、私が会社をやめたあとに誰でもすぐに変更ができるようにしたいと思っています。