Blog

システム開発のドキュメント

  • システム開発
  • Webサイト

ドキュメントの作成

研修がシステム開発になり、早速てんやわんやしています。
どれをとっても初めての連続で、戸惑いながらもなんとか一歩ずつ進んでいます。

今回は、『ドキュメントの作成』~『システム開発』の流れを学びましたので、
『ドキュメントの作成』について、まとめていこうと思います。

今回作成することになったのは、以下の 3 つです。

  • 画面設計書
  • DB 定義書
  • テスト仕様書

作成の過程で困ること、分からないことはたくさん出てきました。

詳しい内容に関しては割愛しますが、記載していこうと思います。

はじめに

まずはじめに、
意識していかなければならないと痛感した重要なことがあります。

以下は、私が画面設計書を作成していたときの話です。

私は、画面設計書のデザインカンプをペイントで作成していました。

「えっ!?ペイント!?」ってなるかもしれませんが、
私が作成していた画面のデザインカンプは
「フォームがあって、ボタンがあって」というような簡素なものだったため、
修正も簡単にできるだろうと高をくくっていました。

そしたら案の定、修正が入りました。

しかし、少しの変更でも 1 から作成というような状態。
毎回毎回なんて、無駄が多すぎてやっていられませんでした。

それに、修正がない完璧なものだったとしても、システムには 『機能の追加』 がつきものです。
その度に、修正が必要なわけですから、、、、Oh…

POINT

結局何が言いたいかというと、
『修正は必ず入る』ということです。

作成するときは、修正するものだと意識して作成しないと
私みたいに大変なことになるかもしれません。

画面設計書

画面設計書で伝えたいことは、以下の通り。

  • 機能は何があり、どういうものなのか
  • 対応しているブラウザなどの情報
  • ルーティングの情報
  • 画面遷移図
  • 各画面のデザインカンプと主要なパーツの情報

POINT

そして、何よりも大切なことは 『これを見れば、作成できること』
「これはどういうこと?」「これはどうすれば?」という質問が出るということは、
まだ完成していないということだと認識するべきだと思います。

DB 定義書

DB(DataBase – データベース)の定義を行います。

  • 使用する DB のスキーマ、テーブルの情報
  • 各テーブルのカラム、およびリレーションの情報

ここの定義に誤りがあると、正常に動作せずに意図しないエラーを吐き出す原因となります。

テスト仕様書

ブラウザテストを行うための仕様書です。

  • 各画面での操作手順と期待動作の情報
  • バグがあった場合の GitHub の issue の情報

ここで注意すべき点は、テストするのは『何も知らない他人』ということです。

POINT

作成している自分が当然だと思うことや知識は一切ないとして作成する必要があります。
そのため、しっかりと操作手順を示す必要があります。

しかし、操作手順の中でも入力に関しては、
入力値を完全に指定しなければならない場合を除き、制限を設けた上で内容は幅を持たせます。

そして、制限で 『エッジケース』 をテストさせることが重要です。
※エッジケース・・・バグが出る/出ないの境界となるケースのこと。
例:一桁の自然数(1 ~ 9)が入力できる・・・「0」、「1」、「9」、「10」

まとめ

  • ドキュメントの修正は必ず入る
  • 何も知らない人が見て、分かる内容である

上記の内容は、とても大切なことではあるが、非常に難しいことでもある。

POINT

そのため、
『必ず他人に目を通してもらう』ことで
内容が適切であるかを判断するのが正しい。


私はこのドキュメントの作成に泣かされたと言っても過言ではないと思います。

しかし、これはプロジェクトがどうこうというだけでなく、
何事においても言えることですね。

自分にしか通じない言葉、知識を前提に話しても誰にも伝わりませんから・・・。

この記事に関しても少しでも噛み砕いて、理解できる言葉で
まとめていけるように気を付けていこうと思います。

最後まで読んでいただき、ありがとうございました。

MeisterGuild(マイスター・ギルド)広報

最先端技術のMEISTERを目指し、お互い切磋琢磨するGUILD、になりたい株式会社マイスター・ギルドです。Webシステム/サービス開発、スマホアプリ開発、AR/VR/MR開発など、さまざまな情報を発信します。

Related Entry