システム開発では、プログラムが動けば完成と考えがちだ。しかし、利用者が操作方法を理解できず、運営者が仕様を説明できなければ、現場では完成したことにならない。
「DX経営ゲーム」では、機能追加が続いたため、実装とドキュメントの一致を改めて確認した。対象は参加者画面、システム仕様書、システム設計書、参加者マニュアル、テスト仕様書だ。
確認した新機能には、AI相談、従業員の採用、結果の原因を考える振り返り、DX効果の可視化、イベント対策要因、製造原価報告書、キャッシュフロー計算書などがある。また、イベントの説明や、履歴APIへ追加された項目も対象だ。
ドキュメントの役割はそれぞれ違いる。システム仕様書は、利用者から見える機能と計算ルールを定義する。システム設計書は、データベース、API、計算エンジン、画面の構成を記録する。参加者マニュアルは、利用者が何を見て、どう判断するかを説明する。テスト仕様書は、どの条件で何を確認するかを定める。
同じ機能でも、すべてへ同じ文章をコピーすればよいわけではない。採用機能を例にすると、参加者マニュアルでは生産能力と固定費の関係を説明する。仕様書では入力値、上限人数、能力計算を定義する。設計書ではデータ項目と処理位置を記録し、テスト仕様書では上限、引き継ぎ、画面更新を確認する。
この役割分担を無視して文章を使い回すと、情報が多すぎる文書と、必要な情報がない文書ができる。文体を変えるだけでなく、それぞれの読者が判断するために必要な内容へ組み替える必要がある。
今回、参加者画面のタブ構成にも変更がありた。AI相談とルール早見表があり、結果画面には製造原価やキャッシュフローなどが追加されている。画面が変わってもマニュアルのタブ一覧が古いままなら、利用者は存在する機能を探せない。
反対に、マニュアルに書いてある機能が画面にない場合も問題だ。自動検証スクリプトが以前の「振り返り」タブを探して警告を出した事例では、現行画面の構成と古い期待値のずれが表面化した。文書やテストも、仕様変更に追随する必要がある。
APIの変更は、さらに見落とされやすい部分だ。結果画面の動的インサイトやDX変革ゲージを表示するため、履歴APIへDX累積値、未充足需要、オンライン販売比率などを追加した。画面だけを見れば新しいカードが表示されますが、設計書へ項目を残さなければ、将来の改修でデータの用途が分かりない。
ドキュメント整合の確認では、名称が書かれているかだけでなく、数値や条件が一致しているかを見る。生産能力は従業員数の45倍、採用上限は5人、イベントごとの倍率、DX変革の条件など、コードと説明が違えば利用者の判断に影響する。
特にゲームでは、仕様を知らない参加者が結果を不具合だと感じる場合がある。採用後に人件費が増えた、DX投資で現金が減った、在庫を持ちすぎて保管費が発生した、といった結果はルールどおりだ。説明が不足すると、正しい挙動と本当の不具合を区別できない。
一方で、ドキュメントに合わせるために実装を正当化してはいけない。実装、仕様、マニュアルの三者を比較し、どれが正しい基準なのかを判断する。コードが動いているからコードが正しいとは限らず、古い仕様を実装し続けている可能性もある。
整合確認では、見出しや検索語を使って関連箇所を横断的に探した。AI相談、採用、DX効果、製造原価、キャッシュフロー、イベントなどの語が、どの文書に存在するかを確認し、その前後の条件を読み比べる。名称だけが一致していても、倍率や上限、対象ターンが違えば不一致だ。
さらに、文書同士が一致していても、実装と違う可能性がある。そのため、画面のHTML、API、データ項目、計算エンジンも確認対象にした。ドキュメント監査は文章校正ではなく、システム全体の契約を確認する作業だ。
今回は、現行のDropbox版を正本として実装を確認し、画面、仕様書、参加者マニュアル、設計書の対応を調べた。確認範囲では、新機能を含む主要な内容が反映され、明確な不一致は見つかりなかった。
ただし、文書整合は一度確認して終わりではない。機能追加時の完了条件へ、実装、テスト、マニュアル、仕様書の更新を含める必要がある。後でまとめて直そうとすると、変更理由や細かな条件を忘れる。
文書は開発の付属品ではなく、システムを運用し続けるための一部だ。機能が動くこと、検証できること、利用者が理解できること、次の担当者が変更できること。その四つが揃って、ようやく開発が一区切りになる。
更新履歴を残すことも、次回の照合を速くするために有効だ。