skillup

技術ブログ

ドキュメント作成

使える設計書作成に関して

投稿日:2020年10月3日 更新日:

私自身、この仕事を7〜8年やっておりますが、設計書作成については常に悩まされておりました。

設計書のメリット・デメリットとしては以下のようなものですかね。

メリット

  • メンバー間での仕様の認識を統一できる
  • 出戻りを防ぐことができる
  • 開発進捗の遅れの影響を防ぐことができる

デメリット

  • 形式的に作られているものも多い
  • 現実の開発との差分が出てしまう(更新する文化が廃れてしまう)
  • 作っても費用対効果が良くない(作る時間に回した方がいい)

デメリットが多くてあまり作ってない現場の方が多かったんですけど、仕様の認識を統一できるというメリットはやはり大きいなと思い、真面目にこの問題に取り組んでみようと思います。

対策

設計書はコードから起こす

現実のシステムとの差分が起こらないように、ER図であればschemaから起こすとか、API仕様書であればLaravelの(Laravel API Documentation Generator)みたいなツールですかね。

要は作るのに手間がかからない、自動化されているのであれば文化として廃れることがないので、これが一番いい気がします。

設計をした方が工数がへる、楽

設計をした方が工数がへる、ラクということになればみんなその通りにやるので、この仕組みを取り入れるのがらくな気がします。

設計→コードの仕組み化

コードから起こすといっても限界があると思うので、ある程度の仕組み化が必要になってくると思います。

一般の仕事の仕組み化と同じですが、できるだけ個人の意識に頼ることは防ぎたいので、レビューのプロセスを経ないと次のプロセスに移行できない。みたいな仕組みとして存在するパターンですかね。

個人的に必要だと思っている設計書について

ダミーデータ付き+テスト仕様書

えーこれはまだ見たことがないので、理想論です。

一般のテスト仕様書って形式的なものが多いと思うのですが、ダミーデータがあれば状態の復元がすぐにできますし、開発をする上でものすごく楽になります。

イメージとしてはPHPUnitの中に組み込む感じで、そこから仕様書を復元できるようにすることですかね。

夢物語と思っていましたが、migrationを組み込んでおけば前提となるマスタデータなどを入れておき、そこからデータを入れることは難しくないのでは・・?と思いました。

API仕様書

昨年度のプロジェクトで作ってました。フロントのエンジニアと一緒に仕事をするときに開発が出来上がってないときに、

  • まずAPIのINとOUTの形だけ決める
  • テストデータでリクエストとレスポンスの形を決めておく

これだけで仕様書の出来上がりです。

グルーピングされたER図

グルーピングということが重要なのですが、ER図があればデータの移り変わりなどがイメージできるのでやはりあると仕様の理解が格段に進みますね。

ER図自体の作成はwinだったらA5SQL、Macならwwwsqldesignerが簡単で便利です。

-ドキュメント作成
-

執筆者:


comment

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

関連記事

no image

小〜中規模程度のWEBアプリ作成で気をつけるべきこと

初見の処理系(ライブラリ操作)などは休日などで最小パターンを確認しておくこと。実務で何時間も悩むと非常にストレスがたまる テーブル設計命。あとで終えるようにトレースができるような値を入れておくこと。 …

no image

新アプリの本番環境デプロイについて

新しく作ったWEBアプリを本番配置しようとしたんですが、何度もやっているはずの処理がいざやろうとするといろいろと手間取ってしまい、1時間近くかかりました。 容量悪いなーと思いつつ、こういった行為はなる …

no image

ファジープロジェクト対策 その1

5月ぐらいから着手していたプロジェクト(顧客管理ソフト)が終焉を迎え、検証段階に入ったので、記して置きたいことなど。 数ヶ月程度ですが、自分が携わったプロジェクトの中では過去最大クラスのものでした。 …

no image

単体テスト仕様書について

おそらく開発者が書きたくないものの筆頭になるかと思う単体テスト仕様書ですが、うまく使うと有益なコミニケーションツールになります。 Contents1 ユーザーのフロー体験・説明書2 前提となるデータ3 …

no image

業務管理アプリの商品コードに関して

一般的な業務管理アプリを作っていると商品や顧客などもオートインクリメントのidではなく、独自の仕様で決められた「商品コード」などを持っていることが一般的です。 昔通販がらみのシステムを使っている時も商 …