*本記事は旧TechblogからCOLORSに統合した記事です。
こんにちは！
エンジニアリングソリューション事業部のS.Rです。
今回は現場で活躍されている皆さんの意見をあつめて
システム開発のドキュメントで何を書けば良いのかをまとめてみました。
設計書の書き方
設計書は、ウォーターフォール型の開発手法において
要件定義書の次に作成するドキュメントの1つです。
設計書はその記載する粒度や内容により、以下に分類されます。
基本設計書
要件定義書で定義した内容に基づいて、システムの役割や非機能要件と言った全体の要件を記載します。
機能設計書
システムの内部構造や動作環境等、どのように基本設計書に記載した内容を実現するかの方式を記載します。
詳細設計書
機能設計書に基づき、プログラム実装に紐づく情報を記載します。
詳細は別の記事にまとめましたので、そちらを参照してみてください。
テスト仕様書の書き方
次に、テスト仕様書の書き方について紹介します。
テストとして単体テスト、結合テスト、運用テストなど様々な工程が存在します。
しかし、それでもテスト仕様書の書き方という点ではそんなに大きな差はありません。
そこで、本仕様書を書く際の最低限のポイントを知っていただきたいと思います。
構成
環境
テストを行った環境の条件(OSや環境変数等の設定)を記載します。
テスト番号
テストを一意に識別するため番号を記載を記載します。
テスト観点
テストで明らかにする内容を記載します。
例：必須で入力しないといけない項目に対して、未入力の場合にエラーが表示されるか 等
テスト方法
テストの方法を記載します。
例：「名前」の入力欄を未入力にして「登録」ボタンを押す 等
想定結果
テストを行った際に、起こる結果を記載します。
例：正常に登録される、登録されずにエラーとなる 等
実施者/実施日
テストを実施した担当者と日付を記載します。
結果
テストの結果を記載します。想定結果と合っているか確認しましょう。
上記のフォーマットが、仕様書としてよく見かける形式だと思います。
ポイントとしては、テストの内容/実施記録を一つの資料で管理できること。
テストデータなどを別紙で用意する場合もありますが、よかったら仕様書を作成する際の参考にしてみてください。
障害票の書き方
設計書に限らず、障害票の書き方も現場によって様々ですが
主に記載する内容は以下の通りです。
構成
発生事象
実際に発生した障害について、ユーザがどの様な順番で操作を行って発生したかをログ解析などをして記載します。
発生理由
障害が実際に発生した理由をできるだけ具体的に記載します。
例：項目に想定外の値が入力されたため 等
直接原因
障害が発生した直接的な原因について記載します。
例：想定外の値が入力されたため、チェック処理でシステムエラーとなった 等
埋込原因
障害が発生した原因についての「なぜ」を記載します。
例：入力される値の考慮漏れが原因だった 等
再発防止策
発生した障害を今後はどうすれば防げるかを記載します。
例：不正な値が入力されていないかチェック処理を追加した 等
基本的には上記を押さえてあれば十分だと思います。
場合によっては補足資料として、横展開調査を行った結果などが必要なります。
マニュアルの書き方
マニュアルとは
作業や操作の手順についてまとめたもの。手引き書・取扱（操作）説明書・手順書など。 [大辞林 第三版] より
マニュアルは、自分が作成して他者が使用するか、他者が作成して自分が使用するか、どちらにせよ作成者と使用者が異なる事が一般的です。
その目的や記載したい内容によって構成が大きく変わるので今回は作る側の留意点を記述致します。
留意点
分かり易さ
当然の事ながら、マニュアルには分かり易さが必要になります。
明瞭な文章に加え、何のための「行動」か「目的」を明示することで、その「行動」の意義が使用者に伝わり易くなります。
使用時の状況
また、マニュアルを作成する上では、使用者側の状況を、ある程度把握しておく必要があります。マニュアルの記載と実環境に差異が無いか、使用者が実際に作業できる状態にあるか、など使用時を想定することも必要です。
マニュアルは、作成者の意図が、使用者に伝わり、適切な行動をとることで意味を持ちます。そのために、「相手側の知っている知識を考え、常に記載する内容を柔軟に変更する」という心構えが重要です。
まとめ
いかがでしょうか。
このようなドキュメントは現場によって様々な書き方がありますが、
本記事の内容を参考にわかりやすいドキュメントを作成していきましょう。
また今回の記事作成に協力していただいた方々、誠にありがとうございました。
