システムエンジニアを始めたばかりの頃はドキュメント作成を任されても何をどう書けばいいかよくわかりませんよね、、
私も基本設計書を書いてレビュー依頼を出しては沢山の指摘を頂き、ヒーヒー言いながら修正しました😅
設計書のレビュー・差し戻しを経験していく中で、私自身が気がついたことや上司からもらったアドバイスを基本設計書を書くときに確認することで、設計書の指摘が以前よりも少なくなりました。
この記事では基本設計書を書くときに確認すべき大切なことを３つ共有させていただきます。
基本設計書を適切に書くことによって、システムの保守性やプログラムをつくるときに悩む必要がなくなるため、より生産性が上がります！
基本設計書を書くときに確認すべき大切なこと
誰に向けて・なぜドキュメントを書くのか考える
作った基本設計書は誰のために・なぜ書くのかを明確にしないと設計書の内容が伝わりにくくなります。
基本設計書は、詳細設計あるいはプログラム製造を行うときに開発者が参考するために書くドキュメントです。
そのため、大雑把な表現や同じ概念を指しているのに少し違う言葉を使わないようにする必要があります。
以下に私が意識していることを列挙します
- プロジェクトに参加したばかりのエンジニアでも理解できる内容・表現であるか
- エラー種別が明確であるか（システムエラー：500, アプリケーションエラー：400 etc...）
- DBテーブルの名前・カラム名が正しい名前か
- プロジェクトで共通して使用されている言葉で書かれているか
データのINPUT / OUTPUTを確認しながら設計する
システム設計では何をしているか一言で言えばデータのINPUT / OUTPUTを定義することです。
どのようなデータを取り出して、編集するのか、ただ表示するのかという出力があるのが一連の流れです。
そのため、基本設計書を作成するときは設計書に書いたデータのI/Oの内容が正しいかSQLクエリを実行してみて確かめます。
再利用できる文章を書く・使う
ある程度成熟しているプロジェクトだと、既に画面・機能の設計書が作られていると思います。
その場合は、他の似たような処理を参考にして書くことでパズルのように設計ができます。
例えば、エラー処理の内容を書くときに毎回自分で書いていたら表現の仕方が何通りもできてしまって複雑な設計書になります。
そのため、エラー処理の時のテンプレートを用意しておいて、エラー種別（システムエラー：500, アプリケーションエラー：400 ) やエラーメッセージの箇所だけ書き換えるだけで良いようにするとより早くドキュメントが出来上がります。
おわりに
設計書を書かないチームもありますが、設計書による言語化は技術力を高めてくれると思います。
まだ私自身新人で設計に関してはわからないことだらけです。
またレベルアップしたら設計書の書き方に関する記事を書きたいと思います。