20代の若手SEが概要設計のコツを書いてみる

はじめに

こちらの記事に触発されたので、私も設計時に心がけていることを書いてみます。
2年ほど設計をメインで仕事しており、そのときに学んだことです。
今は設計から実装まで幅広く担当しています。

エンジニア歴どころか生まれてから20数年の私ですが、全ての設計家(今思いついた言葉)の参考になれば幸いです。

「概要設計」とは？

私が所属している部署には「概要設計」という工程があります。
おそらく「基本設計」と同義だと思います。

あえてその詳細には触れません。
既存のシステムに機能を追加する「基本設計」として以下のコツを読んでみてください。

概要設計書を作成するコツ

①まず概要を簡潔に書く

まず追加する機能の概要を書きます。
ここで長々と書くと設計書を開いただけでオエッとなるので、できるだけ簡潔にまとめます。
2〜3行でまとめられたらGoodです。

②次に機能の目的と理由を書く

概要のほか、その機能を使って何がしたいのかと、なぜそれをしたいのかを書きます。
目的と理由があると内容がスッと入ってきやすいし、レビュアーがその目的を達成するためのさらにいい案を思いついてくれるかもしれません。

目的が複数ある場合は全て書き、それぞれに理由を書きます。

「ユーザーに言われた」「表向きではない別の理由がある」など特別な事情がある場合、理由とは別に「背景」として書くといいです。

③全体を俯瞰できる絵が欲しい

画面追加だったら画面フローのように、パッと見で全体がわかる絵があると詳細を読もうという気になります。

他には業務内容を追加する機能だったら業務フロー、モジュールの追加だったらアーキテクチャ図などが適切かもしれません。
難しいですが、全体の俯瞰図は臨機応変に書くのがいいです。

④絵を多めに

できる限り絵が多い方が読んでもらえるし、正しく理解してもらえます。
まずざっくり絵で表現し、「ここはどうなるの？」と質問されたら追記すればいいと思います。
細かい指摘だったら詳細設計に追記することも考えます。

⑤テンプレなんてくそくらえ

型にはめるとかえって表現しづらくなります。
試行錯誤して自分だけのテンプレを作るのがいいかもしれません。
そして他の人の設計のいいところを見つけて盗み合う。

あとは対応内容によって書く項目が変わるので、そういった意味でもテンプレにこだわらない方がいいです。
例えば機能追加だったら概要から目的、理由まで欲しいですが、単純なバグフィックスだったらバグの詳細と対応方法のみでいいと思います。

⑥時間との戦い

限られた時間内で設計することが多いと思います。
そのためまずテキストベースで全体を作成し、そのあと時間の許す限りで絵を追加するなどリファクタリングしていくのがいいです。

⑦口で伝えた方が早い

最も早い伝達方法は口だと思います。
設計書に残さなくてもいいところは、あえて書かずに口頭で伝えるのもありです。
設計書もシンプルになるので一石二鳥です。

実装者が近くにいない場合はTELしてください。

⑧実装者に考える余地を与える

「iniファイルに○○という設定を追加する」「△△クラスに××というメソッドを追加する」など、ここまで書く必要はありません。
まず概要設計の範囲を超えていますし、何より自分で考えることが少ないと実装者がつまらないです。
概要設計時に「正解」が見つかることも多々あると思います。それでも書いてはいけません。実装者に自分で気づいてもらうことで成長を促します。どうしても書きたければ欄外や詳細設計にでも書いてください。

※私は経験がないのですが、オフショアでPGを外注する場合は詳細までびっちり書かないといけないようです。

⑨リリース後はメンテしない

リリース後までいちいち設計書をメンテしていたらキリがないです。
機能を修正する場合は「機能修正」として新しく概要設計しましょう。
そのときに過去のリンクを貼ると親切です。

⑩そもそも概要設計はなぜ作成する？

概要設計を誰のために、なぜ作成するのか、それを把握して作る意味を知ることは大事です。
これは概要設計に限らず、どんな作業でも同じです。

5W1Hで考えてみます。以下は私の例です。
　　　いつ：業務時間内
　　どこで：社内
　　　誰が：レビュアー(同僚にOKをもらったら上司)、実装者
　　　何を：対応内容の概要を把握する
　　　なぜ：レビュアー 実装の許可を出すため(これ微妙。もっとピンとくる答えがありそう)
　　　　　　実装者 実装するため
どのように：設計書を読んでもらう、口頭で説明する、など

主に上司が確認する資料、とわかればPGの詳細なんていらないことがわかります。
ほかにも過去の設計を読んでこのように対応した理由を知る、などもあると思いますが、
とりあえず一番大きな理由のみ載せておきます。

概要設計の例

仕事以外で設計したことがないので手元に設計書がありません。
反響があればGoogleスプレッドシートなどで作成して載せたいです。

ちなみに仕事ではExcel方眼紙で設計しています。
いろいろ批判があるようですが、仕事のメインPCがWindowsだし使い慣れてるし。
何より他のフォーマットで書いたら上司が「え？」ってなると思います。

え？エクセルはバージョン管理できないって？
コピーして「○○_old_20180223.xlsx」とか付ければいいじゃないですか！
設計書まで細かくバージョン管理する意味ってありますかね？

おわりに

20代の駆け出しSEが書いてみました。
共感・批判大歓迎です。感想でもいいのでここまで読んで思ったことをご気軽にコメントください！

あと以下の観点は敢えて触れていません。

• 表記揺れ
  ユーザーに出すマニュアルではないので気にしなくていいと思います。
  ただし、表記揺れで信用をなくす相手だったら気にしましょう。

• デザイン
  これは「非デザイナー向けの○○」など、偉大なる先人たちの記事を読むのがいいです。
  最低限いえるのは、最初に概要や俯瞰図に目が行くようにしましょう。
  「どこを読んだらいいかわからない」状態になったらオシマイです。

触れちゃいましたね。笑

• 詳細設計
  これはマジで触れません。いつか別記事でがっつり触れたいです。

参考リンク

• 詳細設計書という名のゴミ | Gm7add9
  2019/12/27 追記
  好きな記事だったのですが、リンク切れになってしまいました