プログラミング

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

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

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

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

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

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

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

・はじめに
・背景
・開発方針
・システム概要
・コア・売り・特徴的な機能の概要
・詳細な機能
・テスト
・スケジュール・予算

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

変更前    変更後
Windows7Windows 10
.NET Framework 4.5.NET Framework 4.7

繰り返しと最適化

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

・同じ構成を毎回使う

先輩や上司、関連部門からの指示・ウケが良かった内容は、次回も採用する。

同じ構成を毎回使う

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

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

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

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

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

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

まとめ

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

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

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

応援・要望お待ちしてます

ブログを見ていて「この辺を詳しく知りたい」「このライブラリの使い方を知りたい」「こんなことで困ってる」...etc があれば、コメント・問い合わせ・Twitterで教えてください。質問・ご要望に合わせて解説記事を作ります。

ブログを気に入っていただけたり、「応援してもいいよ」という方がいたら、ブログやSNSでの紹介をお願いします。 あたたかい応援は、中の人の更新の大きな励みになります。

ABOUT ME
えす
現役のソフトウェアエンジニアです。 C++ C# Python を使ってます。10年ちょい設計/開発部門にいましたが、今はQAエンジニアっぽいことをしています。

COMMENT

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です