はじめに ドキュメント管理がされておらず、仕様がわからないツールの対応ばかりをしてきました。 そんな対応はとてもつらく、どうすればこういった辛さを軽減できるのか。 と思い、まずドキュメント管理から、独学ですがUdemyでひとまず学びました。 その内容を個人のメモのために記載しています。 規模も大きく様々なやり方、考え方があるので、あくまで参考程度にして頂ければ幸いです。 手を動かして学ぶITプロジェクトの資料作成！システム開発のドキュメンテーション技術と成果物テンプレート https://www.udemy.com/course/it-yugtl/ なお、ドキュメントの記載方法やFMTはチームごとに違うと思います。 表形式、リスト、図、フローチャートなどなどありますが、結果きちんと記載、確認、共有できれば良いので、どんなドキュメントがあればいいのか？も含めてドキュメント作成、運用しやすいものを選定することは必要だと思います。 0から始める場合に、一番いいのはUdemyの講座の原本やチーム内にある原本から作成を始めることだとおもいます。 プロジェクト計画書 このプロジェクトの目的や背景、ルールなどを記載する。 今後知らない人が確認するときに、プロジェクト開始時の意向や全体像がわかるので方針が決めやすくなると思います。 目的・背景 プロジェクトの目的・背景を記載しておく。 どんな意向があったのかがわかるので、今後知らない人が引き継ぐときに作業方針を決めやすくなります。 本プロジェクトのスコープ 全体の登場人物と流れを記載して、このプロジェクトではここまでを見ます。 という責任範囲を明記する。 きちんと責任範囲を定義することで、仕事の対応範囲を明確にします ソリューション(解決方法) 何を使って何を解決するかを記載する。 この時点では一旦アイデアでもOKで、もし決まってるならそれを記載する。 改善方法をざっくりでもリスト化することで、解決したい課題などがわかるので、具体的な手段のたたき台になる マスタースケジュール ガントチャート的に全体のおおまかなスケジュールを記載する この時点は、おおまかだが、仕様確定のタイミングを決めておくのが大切 タスク・成果物一覧 作りたいツールからタスク、作らないといけないドキュメントの一覧を記載する。 タスクの大枠のカテゴリである「要件定義、設計、移行・運用計画、環境構築・開発、テスト」などに各タスク紐づけて書き、それを各書類の利用用途と合わせて書いておくのが良さそうです。 プロジェクト体制 チーム単位でどこまで何をやるか。という責任範囲をきめて記載しておく。 これがないと収集つかなくなるので大切。リーダーまで決めておくとなお良い。 だれに確認するかなどが分からない時に、チーム単位で責任範囲を確認したりできる。 プロジェクトのルール プロジェクト全体をどう進めるかを可視化し、流れを明確化します。 進捗・課題管理を何でするかの概要。 定例MTGの参加チーム、スケジュール、議題の概要。 MTGで課題があった際のチーム連携の流れ、作業方法の流れ などを記載しておきます。 メール件名とかこまごましたのもあるが、必要なものだけかけばOK 特に定例MTGなどの進捗確認方法が大事。 品質管理方針 ドキュメントでもなんでも成果物に対して、誰がチェックを行い、どう品質を保つのか。というルールを書く。 またどういうものがチェック時にひっかかてるのかを把握すると、全体での認識、共有が深まるのでチェック結果の集計が大切とのこと。 ここで正確な成果物できることで、プロジェクトの想定がより安全になる 要件定義 業務のフロー、それを実現するために必要な機能などを書きだし、設計に必要な情報を可視化します。 業務フロー 実際の業務内容をフローチャート形式にして流れや業務を把握し、課題も記載する。 業務単位の箱ができ可視化することで、現在と将来の箱の数がの増減などが見え、業務の効率化が見えるし、システムの箱が増えたらコストが増えるのでどうするか。 などの指標になります。 業務フローがあっているかは運用チームに確認が必要だが、箱の数の増減でフロー効率化が見込めるか。は自分でチェックができます。 基本的に現在のフロー、将来のフローとそれぞれ記載します。 業務フローをもとに作られる、または紐づく主な資料 業務要件一覧 機能要件一覧 総合テストコンディション・シナリオ定義書 運用作業一覧 業務用件一覧 業務フローの業務内容詳細を表で書き業務の要件の一覧を作成する。 フローと揃うことで、流れ＋各業務の概要が整理できます。 以下のようなものを軸に記載します。 業務名 業務概要 担当 変更区分(変更、廃止、同じなのか） 新旧の差異があるならそれも並べて記載 新フローの業務は機能要件をIDで紐づけたらわかりやすい また、業務用件と機能要件など、他資料と関連付けた方が良い場合は、IDなどで紐づけて記載するといいです。 業務用件一覧をもとに作られる、または紐づく主な資料 業務フロー 機能要件一覧 画面遷移図 総合テストコンディション・シナリオ定義書 機能要件一覧 業務を実現するために必要な機能をリスト化した資料。 将来の新業務フローを見ながら実現するために必要な機能をリストで一旦書きだします。 以下のようにかき分けもするそうです。 FitGap分析前：ただの必要機能リスト FitGap分析後：必要機能リストを実際のツールに寄せて、グルーピングし整理したもの 「FitGap分析前」では「画面、処理、IF」などおおまかな区分わけまでしておくといいみたいです。 書きだした後は業務用件一覧の新ツール関連機能と紐づけると、どの業務にどの機能が使われるのかが、わかるようになります。 ※IF=インタフェース＝外部連携のシステムのこと 機能要件一覧をもとに作られる、または紐づく主な資料 業務用件一覧 機能配置図 テーブル一覧 画面遷移図 画面項目定義書 処理概要定義書 単体テストコンディション定義書 機能配置図 機能要件を参考にどんなシステム(環境)でどうつながっているのか？フローで記載する。 例）Web、メールサーバがそれぞれあり、それがどういうシステムと繋がってるのか？など これがあることで、システムの全体像がつかめます。 また、現在と今後がかけると比較もできていいそうです。 機能配置図をもとに作られる、または紐づく主な資料 テスト計画書 結合テストコンディション・シナリオ定義書 インタフェース(IF)一覧 どんな外部システムとどんなタイミングで連携するのか どんなプロトコルで接続する、データ形式でやりとりするのかなどを書きだす。 このIF一覧をもとにその担当とやりとりするので、システムを漏らさずに記載するのが必要。 なお、この値を～みたいな細かいことは後の設計で記載するので、システムの概要くらいの内容でいいとのこと。 インタフェース(IF)一覧をもとに作られる、または紐づく主な資料 IF項目定義書 機能要件一覧 ライセンス一覧 外部ツールなど契約が必要なものをまとめる。 時間がかかる契約もあるので、キチンと記載する。 開発用のPCとかそういうもの含めて調達しないといけないものを記載する。 非機能要件も考慮しないといけないとのこと テーブル一覧 自分たちが作成、利用するデータベースのテーブルを対象に表で概要を記載する。 作成、利用しないテーブルはキリがないし、そのテーブルが変更になったら資料も修正しないといけなくなるので書かなくていい。 正確な情報にすることが大切。 テーブル一覧をもとに作られる、または紐づく主な資料 テーブル項目定義書 ER図 ER図 データベースのテーブルの関係性を示す図を作成する。 ER図は以下から押さえておくとOK 〇：0 |：1の関係 三本線：多の関係 いろんな作成ツールもありますし、さらなる詳細は必要に応じて調べてみてください。 画面遷移図 業務用件、機能要件作成後に新フローに沿ってフローで作成する画面の遷移図 ER図と画面構成図があれば開発ボリュームはある程度図れるとのこと。 なお、既存の仕組みをそのまま使う場合は作成必須ではない。 非機能要件 業務フローに必要な機能以外の要件を書きだす。 通常時、障害時、セキュリティ、メンテナンス、運用、保守などなどかなりたくさんの項目があり、広範囲で想定しないと書けないので、作成難易度はかなり高い印象でした。 また、これも業務やチームに寄って内容や形式が異なりそうなので、既存フォーマットがある場合はそれに沿って作成。 ない場合はIPAなどを参考に基礎を作成するのが良さそうな印象でした。 システム構築の上流工程強化（非機能要求グレード） ※参考ファイル 「06_活用シート.xls」 （非機能要求グレード本体（日本語版） の一括DL（zip）をDLすると入ってます） 設計 要件定義からツールを作成するための資料を作成します。 設計書を作成すれば、あとは開発するだけでOK。という状態にすることが理想。 IF項目定義書 要件定義で決めたIF一覧から、どんなURL？どんな項目？といったものを決める。 リクエスト、レスポンスの値について記載するが、これはDBのテーブル構造と同じ内容になるはずなので、きちんと決めておくのが良い。 テーブル項目定義書 要件定義で作成したテーブル一覧のテーブルごとのカラム情報などの詳細を記載する 既存の物や把握できないものは記載せずに、作成する分だけ記載するという判断でもOK。 正確な情報を記載することが大切。 テーブル項目定義書をもとに作られる、または紐づく主な資料 テーブル項目定義書 コード定義書 ※データ名を数値などで管理する場合にその情報を記載するドキュメント ※利用ヵ所を把握するために、どのカラムがどのコードIDなのか紐づける 画面項目定義書 機能要件一覧から作成した画面とその構成、処理、項目の詳細情報を記載する。 画面の処理や仕様が分かればOKなので、以下のような情報を記載します。 既存画面がある場合は画面のキャプチャー画像 新規画面の場合は簡単な図形で画面のパーツ構成が分かるように記載 画面の遷移元、遷移先 画面項目（テーブル項目定義書と同じように書く） 処理概要として、この画面の処理の内容、トリガー、リクエスト、エラーなどを記載 ※処理概要は別ファイルの「処理概要定義書」に記載してもOK これを見て画面ごとに構成、処理の内容が分かるようにすることが大切。 画面項目定義書をもとに作られる、または紐づく主な資料 機能要件一覧 単体テストコンディション定義書 コード定義書 ※データ名を数値などで管理する場合にその情報を記載するドキュメント ※利用ヵ所を把握するために、どのカラムがどのコードIDなのか紐づける 処理概要定義書 ※画面項目定義書に書けない処理を記載する 標準パラメータ定義書 クラウドシステムやパッケージの機能を使う場合に作成する。 利用に際して設定した項目の値を記載し、今後のために情報を残しておく。 処理概要定義書 機能要件一覧のIDと紐づけて、機能詳細を記載する。 画面項目定義書で処理概要もあるが、どっちかにかけばOK 分かりやすさ重視。プログラム書くときに仕様がわかりやすいように記載する。 主に以下が分かれば良さそうです。 トリガー リクエスト、レスポンス 処理内容 エラー これを見て処理の内容が分かるようにすることが大切。 処理概要定義書をもとに作られる、または紐づく主な資料 単体テストコンディション定義書 機能要件一覧 コード定義書 ※データ名を数値などで管理する場合にその情報を記載するドキュメント ※利用ヵ所を把握するために、どのカラムがどのコードIDなのか紐づける コード定義書 データベースやプログラム内の値をコードで管理する場合に記載する。 データをコードで管理する事で名前の変更に耐えれるが、ぱっと見わからなくなるので設計書にかいておく 使われる場所がわからないといけないので、テーブル項目定義書、画面項目定義書でIDでつながるように紐づけて書いてあげるのも大事。 コード定義書をもとに作られる、または紐づく主な資料 テーブル項目定義書 画面項目定義書 環境設定定義書 インフラ情報を管理するために必要な情報を記載する。 環境構築時に設定した値を記載し、今後確認できるようにしておく。 テスト 設計書から作成したツールのテストをする場合に必要なドキュメント。 ポイントはプログラムからつくるのではなく、ドキュメントから作成するという点。 ドキュメントにプログラムを合わせていくのが大切です。 テスト計画書 テスト全体の概要などを記載します。 主に以下の内容を記載します。 テストスコープの定義 機能配置図から機能ごとにどんなテストをするのか？を記載します。 フローチャートで単体、結合、統合などを色分けで書くとわかりやすいです。 なお、テストは以下のようなものがあります。 単体テスト 設計書に定義した機能がすべて正常に実装されていることを確認する。 設計書に定義した処理の全パターンを網羅すること 結合テスト IFなど連携先のINとOUTにある機能が、互いに整合のとれた設計になっていることを確認する IF定義書に定義したデータパターンを流通するテストを実施 総合テスト 業務フロー、および業務一覧に定義した業務がすべて行えることを確認する 受入テスト 総合テストと同じようなことを依頼元で行う 開始条件と完了条件 単体テスト、結合テスト、統合テスト、受入テストの開始条件と完了条件を表で記載する。 例えば単体テストの条件なら以下のようなものがあります。 開始条件：全ての開発が終わっている 完了条件：定義した条件をすべてクリアした、不具合の発生頻度が収束した。 基本的に前段階の作業が完全に終わっている、定義した条件をすべてクリアしている、ある程度の期間利用し、不具合の発生件数が収束してきている。というのが基本的な条件になると思います。 テスト実施スケジュール テスト期間とその間の移行リハーサルのスケジュールを記載する。 各フェーズでの重要な条件となることの完了予定も記載しておくのが大事。 また移行リハーサルを統合テスト前に行う。 移行とはデータの移行など旧→新へ移行するときの作業のこと。 障害管理プロセス 障害が発生した際の担当の流れを記載する。 誰が何をするのか？がフローでわかればOK。 テスト実施体制 今回のテストにかかわるチームの関係性が分かるように記載する。 テスト期間中の情報連携 テスト期間中の定例MTGなどどういったサイクル、議題、目標で行うのかを記載しておく 単体テストコンディション定義書 機能単位のテストの条件を書き出し作業用のリストを作成する。 機能要件一覧、画面項目定義書、処理概要定義書を軸に項目、処理機能ごとに記載する。 通常？異常？ 必須？必須じゃない？ 登録、削除、更新はできるか テストに使うデータ など各処理とテストデータを記載していきます。 またテスト時の入力値は最小値と最大値や、機能の条件をが満たせるのが良い。 なお、インタフェース(外部連携)機能は結合テストでするので、ここはあくまで今見てるツールの動作だけでいいOKです。 IFが完成してない場合は、スタブ(値だけ返す仮のインタフェース)を簡単に作成しておく また最大のポイントはプログラムをみて設計書をつくらないこと。 設計書から作成し、設計書どおりに動いてるか複数回数日に分けて確認する。 単体テストコンディション定義書をもとに作られる、または紐づく主な資料 機能要件一覧 画面項目定義書 処理概要定義書 結合テストコンディション・シナリオ定義書 単体テストと違い、複数の処理を組み合わせたテストです。 そのため複数項目を経てOKとなることが多いです。 テストを行うためのテストシナリオ(操作手順ごとにテスト項目を並べたもの)を機能配置図、機能要件一覧を基準に作成します。 コンディションシートで項目を網羅的に書きだし、シナリオシートでそれを体系的記載します。 1つのシナリオで全部しようとすると書けないので、1つずつ書いて、いくつかシナリオを分けて作成します。 入力値などサンプルデータの作り方は単体テストと同じ感じです。 結合テストコンディション・シナリオ定義書をもとに作られる、または紐づく主な資料 機能配置図 機能要件一覧 総合テストコンディション・シナリオ定義書 将来の業務フロー全体を通すテスト、すべての業務用件が実施できるか確認する 業務フローの数だけ、シナリオもできます。 気付けないことがあるので、データは本番に近いのが良いです。 また総合テストでプログラムのバグがでるのはかなりまずいことなので、それがないように前段階のテストはしっかりしておきたい。 出るべきバグは設計や仕様で漏れていたそもそも想定されていないこと。 総合テストコンディション・シナリオ定義書をもとに作られる、または紐づく主な資料 業務用件一覧 業務フロー 障害一覧 テストの結果を表でまとめて記載する。 まとめることで一日あたりの障害数が減ってるかみれたりするし、書く人、直す人が作業しやすくなる。 どのフェーズ？(単体？結合？統合？) 事象 どの段階？(要件?設計?など) 原因 解決方法 などを書いておくと良いです。 障害一覧をもとに作られる、または紐づく主な資料 単体テストコンディション定義書 結合テストコンディション・シナリオ定義書 総合テストコンディション・シナリオ定義書 移行計画 旧システムから新システムに移行する。 または新システムを導入する方法を正確に記載する。 移行計画書 旧システムから新システムに移行、または新システムを導入する方法の計画書。 主に「業務、システム、データ」のカテゴリで流れ、移行方法、懸念事項を把握しながら記載します。 また新規システムだけならいいが、旧システムが絡む場合、移行するデータの選別、仕様を把握+データの不整合が起こらないように慎重に決めないといけないので、 かなり慎重に計画を作成する必要があるので、移行手順を作成し、総合テスト前に移行リハーサルを行うことは必須になります。 移行計画書として作成する主な内容は以下の通りです。 移行方針の概要 業務、システム、データで何をどうして、どう移行するのかの概要 業務上やデータの整合性を保てるような方針にする。 移行対象データ一覧 移行すべきデータをすべて確認し、移行方針、移行方法を記載する 移行スケジュール 移行全体のスケジュール。 結合テストの段階で調査、手順書の作成を行い、総合テストの前に移行リハーサルをするようなスケジュールが良い 移行体制 移行にかかわるチームを記載する 移行手順書 移行計画を実行するために、いつまでに、どういうやりかたで進めるのかを見ただけでできる状態にまとめておく。 旧システムから引き継いで移行する場合は特に複雑化するので、総合テストの前に本番と同じ移行作業をリハーサルしながら作成する。 もっといえば何時何分～何時何分でこの作業をおこなう。というのも書いておいた方が良いみたいです。 テストコンディションと同じように誰が何をしたがわかるようにリストで作成する 運用計画 システム完成後の運用の作業の一覧やマニュアルを作成する 運用作業一覧 システム完成後の運用の作業の一覧を記載する。 例えば、ユーザ登録、削除、障害対応、仕様変更(追加開発)などがあり、項目としては作業項目、頻度、作業概要などを表で記載する。 運用作業マニュアル 運用の作業一覧の業務を見ただけでできるようにする。 定期作業は特に開発できない人たちにやってもらうこともあるので、詳細に手順を記載しておく必要があります。 ドキュメントをみて運用作業、ドキュメント更新ということを徹底する。 なお、運用という枠に開発の改修なども入る場合もあるそうなので、その場合は開発が仕様を把握できるようにドキュメント管理を行うといいと思います。 障害報告書 障害が起こったときにその原因→解決方法をを記載していく。 難しい+スピードが必要な作業で限られた人しかできないので、原因→解決方法を簡潔に記載しておくことで、今後誰でもできるように、または解決しやすくする。 主に以下の内容を残すと良さそうです。 発生事象 発生原因 影響範囲 暫定対応 根本的な原因 本格対応 プロジェクト管理 プロジェクトを管理するための方法、ドキュメントを作成する。 WBS 全部のタスクについて、だれが何をいつからいつで行うのか+進捗がわかるものように管理しておくことをWBSという。 案件が始まるときに作成し、要件定義が決まったらブラッシュアップするのがいいみたいです。 チームによってさまざまだと思うが、ガントチャート的なフォーマットが多いと思います。Backlogなどのツールもあるのでそういったものを使うケースもあると思います。 TODO・課題一覧 WBSの漏れなどの問題、誰かに聞かないとわからないことなどが起こったらそれ課題として表に記載していく。 TODO(やればおわること)や課題(予想されるリスク、懸念)を記載し事前に認識しておくことで事故を防ぎます。 レビューシート 成果物のレビューを表で残す。 成果物のチェックレビューを残すことで、間違いが多いものなどの傾向を知ることができる さいごに 学んだ感想としては、この書類があり、きちんと見る方法、更新方法を教えていければ、仕様の引継ぎ把握は格段にしやすくなるのではないかと感じました。 一方でドキュメントの量がとても多く、整合性を保つ難しさも感じたので、プロジェクトチーム全体でどれだけ意識をたかめてドキュメントの見方の説明、作成、更新していけるか。が非常に難しく、大変なことだと思いました。 ひとりでは作成できないので、繋ぎ、まとめ役、各専門家の連携は必要だと思います。 またどちらにしてもプログラム内にはちゃんと実装背景、理由などコードから読み取れないことをコメントで残しておくことも必須だと感じました。 率直に量が多い！！大変だ！！ 開発より時間をかけるというのもうなずけます。 目次だけでも見るの大変ですが、全体をつかみたいときは目次見てください。 今回勉強して一番響いた言葉は 「プログラムからドキュメントを作成しない。ドキュメントにプログラムをあわせる」 でした。 本当大事。