Tetoatomです。
いまどきのWEB系、アプリ系の案件ではどのようなアウトプットドキュメントを求められるのかわかりませんが、私が経験した多くの組み込み系の案件では、ウォーターフォール通りに基本仕様書を作って詳細設計書を作って、単体項目書、結合項目書を作成します。
ウォーターフォール開発モデルを採用した多くのプロジェクトは多くの場合、以下のフェーズで開発が勧められていくでしょう。
要件定義 → 基本設計 → 詳細設計 → 製造 → 単体試験 → 結合試験
基本設計
基本設計というフェーズで作成する基本仕様書は要求定義の整理や実現方式のブレイクダウンを記載するので、多くの場合、有用です。
具体的には機能間やタスク間の関係を表現したりするためにシーケンスを作成します。
知識のない人や、当該機能に関係ない人が見てもその機能の概要を理解するためにも基本仕様書が必要なシチュエーションは存在します。
その為、直接的に実装に影響しないけど、レビューアにわかりやすくするために記載するような情報も存在します。
内部の処理がわかっている人からしたら、わざわざ書かなくてもわかるでしょというようなレベルでも、説明のため、理解してもらうためにはわざわざ書くのです。
仕様書は実装のためだけではなく、関係の無い人も含め、他人に理解してもらうための情報を肉付けして作成する場合もあるのです。
これによって、そもそも要求としている情報の整合性が第三者視点でもチェック可能になってきます。
ワタシ的にはこのフェーズで書くドキュメントはある程度読み物としての制度も必要だと思っています。
詳細設計
今回、考えたいのはこのフェーズで書くべきドキュメントです。
私が経験した多くのプロジェクトではフローチャート（UMLならばアクティビティ図）が求められます。
フローチャートによって、レビューアが視覚的に処理の流れを判断できるからです。
私の経験上の話なので、非常に狭い話ですが、WEB/アプリ系の方にこの話をすると鼻で笑われる場合もあります。
私の考えとしては、フローチャートは絶対に要りません。
フローチャートはグラフの中でも、かなり書くのが面倒な部類だと思います。
バグに対する修正も大変です。フローチャートはかなりソースと１：１に近い関係になっているため、ソースのバグによるフィードバックが必要なケースが多々存在します。
コーディング中に思いついた効率的な関係で、処理順序を変えたいという時もソースと１：１になっているため、フローチャートも修正しなければいけない場合があるのです。
逆にフローチャートを神様とするほうが良いため、フローチャート修正を考えるなら非効率でもソースもそのままにするなんて事態も起きてしまいます。。。
基本設計まではわかります。
外部の人間もチェックする必要があるシチュエーションについての重要性は理解しています。
詳細設計はもう、そういう観点でのドキュメント作成はいらないと思います。
実装ができるために、内部の人間だけがわかって、実装情報の整理のためだけのメモ書きになってさえいればいいと思っています。
ものによっては全く不要だと思います。
よく、デバッグ用に空でプログラム組むなんてよくあると思います。
まあ、これは極論ですが。。
プロジェクトには経験の浅いメンバもいることでしょう。
だけど、その人間にレベルを合わせていては作業量も増えますし、よりよい実装に結びつきません。
下の人間は上の人間を見て、理解しようとしなければならないと思います。
詳細設計以降は設計者のレベルで、必要最低限の情報量で設計者本人が実装できる情報が整理されていれば良いと思います。
経験の浅いメンバはどうすればよいか。
はじめのうちは、機能実現のための実装は経験者が実施し、フェールセーフなどを考えた異常系の実装についてのみ作業すればよいと思います。
あとは、設計者が書いたソースをよく読んで、吸収していくことです。
私の経験上、経験の浅いメンバに合わせてものを作っていくと、時間がかかる、そのメンバが成長しない。という結果に至りました。
（私の経験なので、もちろん偏っていると思います。）
ダメなリーダーについているメンバほど成長するなんてことはよく耳にしますが、これは本当だと思います。
「自分がやらなければ」という状況が作れれば、ほぼ能動的に作業しようとする動きが見えてきます。
まず、これらの前提がある中で、最近私がハマっているのはDoxygenです。
Doxygenで設計する
いまや、Doxygenそのものの説明は不要かと思っています。
ソースコードに記載したコメントに特別なタグを付けることで、そのコメントがドキュメントとして出力されるツールですね。
「Doxygen」
これをうまく使うことで、経験上フローチャートを書くよりも作業時間を減らせており、かつコーディングする人へのインプット材料としても有益なものとなりました。
ソースに記載しているため、ソースとほぼ１：１となっている為、コーディングする人の理解度が低くてもわかりやすい、かつソースとドキュメントが１：１になっているのに、実際にはソースコメントであるため、コーディング時に判明した問題をフィードバックしやすい！！
私は結構好きです。Doxygen。
Doxygenを使わせてもらう
私が、一番この記事で書きたいことは、どうやってうまく書くかではありません。
経験を詰めば最適な方法はいろいろと思いつきます。
しかし、大きなプロジェクトになると、その新しい方法を使用した開発が許されない場合があるのです。
その方法で開発を進められるように、どうやってお客さんを納得させるかです。
特に古くからあるプロジェクトでは、伝統があったりして、開発作業で「よくわからないが、前のプロジェクトでもそうだったので」がよく許されます。
正しくは、「前のプロジェクトでこういう理由であり、このドキュメントにこのように記載されているので」となるはずでしょう。
まあ、実際ここまでの回答するのは面倒でしょうがないでしょう。。
新しいことを取り入れいく事自体が「悪」と考えられていく場合もあるのです。
ただ、そのプロジェクトで実現すること自体は世界的にも初で注目されいるにもかかわらず、開発作業自体は古臭いやりかたであり、大炎上なんてことも。。。
今後、プログラマの能力が底上げされ（小学校からプログラミングを習うなんて話もあるし）求められる要件は増えていくでしょう。
工数据え置きで。。
私はとにかく自身を持って、今までの経験で培ってきたものをプレゼンしていきます。
Doxygenにかぎらず、さまざまな開発スタイルを実践したい場合、とにかく自身を持って、自信を持てるだけの情報を持って、アピールすることです。
そのことに対して、メリットもデメリットについても理解してなければなりません。
当然デメリットがあるならば、対策を考えておく必要があります。
中途半端な知識では、そのプレゼンは通らないでしょう。
とにかく、自信を持つことが必要ですね。
私が携わったプロジェクトではフローチャートを廃止し、Doxygen一本にするようにしています。
実際、かなりの工数削減につながりました。
次は単体試験をどうにかしたものです。。。