こんにちは、まつけんです。Webエンジニア11ヶ月目です。
最近、初めて詳細設計（上流工程）にチャレンジして、先輩方からもいい感じに褒めてもらい、その際に意識したことをできるだけ言語化して、まとめてみました。
▼週間MVP。嬉しみが深み
この記事が参考になりそうな読者
- 上流工程（詳細設計）にチャレンジしたい歴の浅いエンジニア
- エンジニア1年目がどんな意識で詳細設計に取り組んだのか知りたい人
詳細設計でバリューを出すためにやったこと5つ
結論です。
- 目的を明記する
- 絵（図・表・画像）を使う
- 共有を早くして、フィードバックをもらう
- 表記揺れを無くす
- 1晩寝かせる
「詳細設計とは？」という方へ
「詳細設計知ってるぜ！」という方は読み飛ばしてください。
▼以下のシステム開発の流れの「3. 」の部分をやりました。
- 要件定義
- 基本設計
- 詳細設計←ここにチャレンジしました
- プログラミング（実装）
- 単体・結合テスト
- 運用
詳細設計は、ひとことで言うと
- エンジニア向けのドキュメント。システム内部の動作、機能、DBなどの設計書。
例えば、以下のような流れです。
- 【要件定義】 → カフェのメニュー選択や注文の確認・変更などを簡易にしたいというカフェオーナーからの要望。
- 【基本設計】 → タッチパネルで操作する注文システムを作る。主要な画面を設計。（メニュー一覧、注文確認、合計金額表示など）
- 【詳細設計】 → 画面設計：メニューのアイコンや価格、注文ボタンの位置。
処理の流れなどを明記：メニューをタップ→数量選択→注文確認→合計金額の計算と表示。
この際Menuテーブルのnumberカラムを参照して、数量は表示する等々。 - 【プログラミング（実装）】 → タッチパネルの反応、画面レイアウト、金額計算のプログラムを作成
- 【単体・結合テスト】 →単体テスト：メニュー選択や金額計算の動作確認。
結合テスト：一連の注文プロセスを通しての動作確認。 - 【運用】 → カフェでの実際の運用を開始。
▼このサイトの説明が分かりやすい
1. 目的を明記する
これ1番重要だと思うので、最初に書きます。
目的を明記するのは、以下の理由からです。
- いざ実装に着手してから、「あれ？、これって何のために作るんでしたっけ？」ていうコミュニケーションコストを減らせる
- 「この目的ならこんなアプローチでもいけるんじゃね？」という生産的なフィードバックを先輩エンジニアからもらえる可能性上がる
- 「何のために作る機能なのか」を分かっていないと、エンジニアの開発モチベーションが上がらない
最大の理由としては、
「何のために作る機能なのか」を理解してないとエンジニアの開発モチベが上がんないから
ですね。
僕自身、実装する側になったら、「何のために作る機能なのか」を必ずインプットしてから実装に着手するので、他のエンジニアさんもきっとそうだろうと思ってます！
▼Twitterで流れてきて10回いいね
押したくなったツイート
まとめ：目的 is 正義。
2. 絵（図・表・画像）を使う
やっぱり、言葉だけのドキュメントより図・表・画像などを使ったドキュメントは、見やすく理解が早いと思います。
心理学的にも効果が立証されているようで、以下の結果が得られたそうです。（絵を用いた方が記憶に残るみたい）
【言葉だけのプレゼンと絵を用いたプレゼンを比較した時】
言葉だけの伝達では72時間後、そのうちの10%しか記憶に残っていないが、これに絵を加えた場合、65%が記憶に残るとのことである。
参照：画像優位性効果
例えば、
▼以下が文字だけの伝わりにくい
パターンです
Userテーブルにroleカラムを作ってください。roleカラムはString型です。
roleカラムにはステータスを持たせたく、Profileテーブルのuser_statusが1の場合administrator、２の場合guest、３の場合active_user、４の場合end_userです。
▼以下が表を用いた伝わりやすい
パターンです
Userテーブルにroleカラムを作ってください。以下の表が詳細です。
| 追加するカラム名:role | roleのステータス | roleのステータスの条件 | データ型 |
|---|---|---|---|
administrator |
Profileテーブルのuser_statusが1の場合 | String | |
guest |
〃 が2の場合 | 〃 | |
active_user |
〃 が3の場合 | 〃 | |
end_user |
〃 が4の場合 | 〃 |
文字だけのパターンは正直読む気が失せる感じ。。。
一方、表を用いたパターンはパッと見でなんとなく概要が分かって、文字だけの時より、めっちゃ読む気が出てくる。
同じ内容でも伝え方で、受け取り方は全く違ってきますよね。
まとめ：絵しか勝たん。
3. 共有を早くして、フィードバックをもらう
どんな仕事にも言えますけど、「共有・相談」は早い方が良い 
なぜなら、細かな認識のズレなどを周りと調整しながら仕事を進めれるから。
例えば、以下のAさん・Bさんのパターンだと、たぶん成果物はBさんの方が良いモノができると思います。Aさんの場合、大きな手戻りが発生する確率が高くなります。
Aさん：設計書が100％完成してから、先輩に見てもらう。
Bさん：設計書の大枠を20、30％くらい作ってから、やることの詳細を先輩に共有。
僕の場合、既存のテーブルにカラムを追加する詳細設計をやっていて、
- カラムに値を保存する時のバリデーションはどうする？
- カラムにAの値を保存する条件は〇〇で、Bの値を保存する条件は▲▲で大丈夫？
- この場合、カラムのデータ型はInt型で大丈夫？
など多くの疑問が、詳細設計書を書く前に湧いてきました。
なので、先輩からフィードバックを受ける時間を作ってもらい、認識のズレなどがほとんど無くなった状態で詳細設計書を書くことができました。
▼マコなり社長のツイートが刺さった。大共感。忘れたくないので、引用として載せます
「共有を早くする」に関しては、僕もまだまだと感じています。実装の時もたまに悩み込む時があって、早く先輩に相談しとけば良かったな〜と思う事例がポツポツ思い当たります。
改めて、「共有を早くする」ことに関して、身を引き締めて取り組みたいなと思い、本記事に書きました。
まとめ：共有は早いに越したことはない
4. 表記揺れを無くす
これは僕が文章を書くとき、地味にこだわっている点です。
表記揺れ（ひょうきゆれ）とは、同じ意味を表す言葉なのに、さまざまな表記が混在している状態です。
例えば、以下の2つの例です。
ダメな例では「スマホ」と「スマートフォン」が混在し、読み手に負担がかかります。
一方、良い例では「スマホ」の表記が一貫しているため、文章の流れが自然で読みやすいです。
【ダメな例】
- 今日はスマホを新しくした。店員さんが最新のスマートフォンの機能を詳しく教えてくれた。新しいスマホは非常に反応がいい。特に、このスマートフォンのカメラ機能が気に入った。
【良い例】
- 今日はスマホを新しくした。店員さんが最新のスマホの機能を詳しく教えてくれた。新しいスマホは非常に反応がいい。特に、このスマホのカメラ機能が気に入った。
詳細設計以外のことでも言えるんですが、いつも文章を書いた後に読み直して、同じ意味で違う表記の言葉がないかを確認しています。
こうすることで、表記揺れが無くなり、読み手に負担のない文章を書ける気がしています。
余談ですが、僕はDB設計に絡んだ要件の詳細設計を書くとき、「DB」と「データベース」が混在しそうになりました。。。
ちなみにこの記事も表記揺れを無くそうと、読み直してます。あったら編集リクエスト送ってください（笑）
まとめ：表記揺れは無くそう！
5. 1晩寝かせる【小ネタ】
「1晩寝かせる」は自分だけかもと思ったので、小ネタ枠として紹介します。
書き終えて、読み直したのに1晩寝かせて翌朝に文章を見ると、高い確率で推敲（すいこう）できる箇所が見つかるのは僕だけでしょうか？
例えば、今回チャレンジした詳細設計でも
夕方くらいに、
僕「よっしゃー全部書き切った！レビューしてもらいたいし、さっそく共有しよっと。 でもみんな退勤してるし1晩寝かせて、翌朝見直してから共有しよう。」
翌朝にその文章を見ると、
- 誤字・脱字が見つかったり、
- もうちょっと伝わりやすくなる表現で書けたり
色々と推敲すべき箇所が見つかりました。
という感じで、読書のあなたも余裕があったら完成した資料は1晩寝かせてみてください。
実はこの記事も1晩寝かせてます(笑)
▼調べてみたら「1晩寝かせる」はトッププロライターも実践してるみたいです。
※推敲・・・詩や文章をよくしようと何度も考え、作り直すこと。
終わりに
今回は詳細設計（上流工程）に初めてチャレンジしてみて、大変なこともありましたが、他のエンジニアさんに知識の共有などで協力いただき、期日までに完了できました。
実装する時とは違う頭を使っている感覚で、普段から詳細設計をゴリゴリ書いている先輩エンジニアさんのすごさをより体感しました。
これからも実装以外のことにもどんどんチャレンジして、できることを増やしていきたいと思ってます。
詳細設計に限らず、初めて新しい仕事にチャレンジする若い人は、特に「共有を早くして、フィードバックをもらう」に関しては、マジでみんなやったほうがいいです！
詳細設計するとき、役に立った記事
▼こちらの記事が詳細設計のドキュメント作成で大変役に立ちました。