【設計書の書き方】ソフトウェア 設計書のコツ

最近仕事で設計書などのドキュメントを見たり、作成者の相談にのることが多くなってきました。
今回は自分が10年数年S/Wエンジニアをやってきた経験から、設計書を書く際のコツについて書いてみたいと思います。

注意：伝統的なウォータフォールの確認・承認がはびこる世界のお話です。
　　　アジャイルでフラットな方々は、遠い異世界の話として見ていただければ幸いです。

結論「自分なりのフレームワーク(型)を持つ」ことがコツです

ソフトウェアに関わっていると、「新規開発」「機能追加」「不具合修正」「機能改善」など、様々なプロジェクトで設計書を書くことが多いと思います。

プロジェクトの性質によって書く内容は違ってきますが、プログラミング同様、抽象化してみると
書く内容は同じような構成にできることが多いです。そこで、過去に自分や前任者が書いた設計書から、大体同じようなことを抽出してフレームワーク(型)を作ってしまいます。

個人的には以下のような構成を使用しています。あとはプロジェクトに合わせて、
機能の部分を「追加/修正する機能」にしたり、テストやスケジュールを別文書に移動したりして使っています。テンプレとも言えますね。

以下のように使用等の比較表なども、書くことが多いんじゃないでしょうか？
こういった表や図なども、サイズや罫線、配色を型として決めてしまいます。

繰り返しと最適化

フレームワーク作ったら以下のように運用していきましょう。

同じ構成を毎回使う

自分なりのフレームワークを作成したら、それをベースに設計書を作成しましょう。
ここで重要なのは、一度OKをもらえたフレームワークは、あまり変えずに次回も使い回すことです。

使い回すことで同じ指摘を受けることも減り、読み手側も「ああ、前と同じね」と流れをつかみやすいので読むのが楽になります。
逆に大きく変えてしまうと、読み手は「今回は何を書いたんだ？」から始まるため指摘(とイライラ)も増加していくことになります。

査読や確認に慣れていない方は、前回と同じライブラリを使う他人のコードと、毎回違うライブラリを使う他人のコード、どちらを読みたいかをイメージするといいかも知れません。

指示あった部分・ウケが良かった書き方は次回も採用する

査読や確認の中で、「ここはこう書いてくれ」「ここはいいね」などの話があった部分は、次回も忘れずに採用するようにしましょう。内容以外にも、配色、インデント、罫線なども重要です。

「そこまで媚売らなくても」と思うかも知れませんが、読み手は意識的/無意識に見ているため効果的がありますし、自分のスタイルを取り入れてくれた事を悪いと思う人間はいません。気づいていないようであれば自分から言い、再発防止アピールとするのもアリです。
また、オリジナリティは文書が「読まれた先」の「設計内容」で発揮するものなので、
配色や罫線や書き方であれば、どんどん読者にすり寄ってあげましょうw

まとめ

時には使い回せないこともあります

ここまでで使い回しが重要といってきましたが、
プロジェクトや上司、組織が変わると、作り上げたフレームワークがまったく受け入れられないことも出てくると思います。その時は一度既存のフレームワークを頭の片隅においやり、一から改めて作り直してしまいましょう。
S/Wと同様に、全ての環境で使用可能なフレームワークはありません。また、複数のフレームワークを使いこなすことができれば、対応できる環境や文書の幅もどんどん広がります。
文書はあくまで設計内容を伝えるための「伝達手段」に過ぎませんし、
一つものに固執して対立を生むのであれば、さっさと作り直して最適化してしまい「設計の中身」に注力することが大切なんじゃないかと思います。

だいぶ抽象的で分かりづらい点もあるかと思いますが、
誰かの参考やヒントになったらうれしいです。

質問・要望 大歓迎です

「こんな解説記事作って」「こんなことがしたいけど、〇〇で困ってる」など、コメント欄で教えてください。 質問・要望に、中の人ができる限り対応します。

使えたよ・設定できたよの一言コメントも大歓迎。気軽に足跡を残してみてください。記事を紹介したい方はブログ、SNSにバシバシ貼ってもらってOKです。