開発文書に変更履歴は何故必要なのか？重要性と記載する際のポイント

背景

開発プロジェクトでは、文書化が極めて重要です。その中でも特に変更履歴の重要性は高いと言えます。変更履歴は、開発者や利害関係者に過去の変更を理解する手助けをします。本記事では、開発文書における変更履歴の役割と、効果的な書き方について解説します。なお、本記事では、要求仕様書/機能仕様書/設計書/評価仕様書などを総称して開発文書と呼んでいます。つまり、開発に関与する全ての文書のことです。

変更履歴がないとどうなるのか

変更履歴は、開発文書において欠かせない要素です。なぜならば、変更履歴がないと、以下のような問題が発生します。

• 過去の変更の理解が難しい
• バージョン間の差異が不明瞭
• 変更点を抽出するのが困難

変更履歴の記載ポイント

効果的な変更履歴を作成するためのポイントは以下3つです。

• 日付とバージョン番号の明記: 日付と対応するバージョン番号を明示することで追跡を容易にします。
• 変更の具体的な内容の記述: 変更内容を具体的かつ簡潔に記述し、誰でも理解できるようにします。
• 変更のカテゴリを明確にする: 変更が機能追加、修正、削除などのタイプであるかを明確にします。

上記記載ポイントを意識して作成した変更履歴の例を以下に示します。

変更のカテゴリを明確にしておくことで、後工程の方が変更の内容を理解しやすくなり効率化に繋がります。特に「追加」に関しては日程へのインパクトが懸念されるため、優先度高く内容を見ることになります。「明確化」という言葉は聞きなれないかもしれませんが、仕様を定義する側にとっては便利な言葉です。例えば、「修正でも追加でも削除でもないが、問い合わせがあったので誤解を招く表現を修正したい」というときに使います。備考列を設けていますが、変更の要因となった情報を残すのに便利です。例えば、例に記載したように管理番号を記入しておくことで、修正の意図や背景が後で追跡できるようになります。

バージョンの付け方

変更履歴の記載ポイントで触れましたが、変更点と開発文書のバージョンを紐づけるべきです。その際、バージョンの付け方に意味を持たせることも重要です。例えば、以下のように数値の桁毎に意味を持たせることが多いです。

上位文書の発行毎に更新

開発文書が以下のような構成の場合で考えてみます。

・上位文書：システム機能仕様書

・設計工程①：ソフトウェア要求仕様書

・設計工程②：ソフトウェアアーキテクチャ設計

・設計工程③：ソフトウェア基本設計

・設計工程④：ソフトウェア詳細設計

上位文書であるシステム機能仕様書のバージョンが更新された場合に番号を更新します。つまり、この桁ではソフトウェア開発の入力情報を管理していることになります。ソフトウェア開発のベースラインを意味する重要な番号となります。突然システムという言葉が出てきましたが、ソフトウェアとハードウェアを含む製品としての振る舞いを記述した文書という位置付けです。

設計工程毎に更新

仮に、設計工程①と②を同一文書内で表現するスタイルの開発文書である場合、設計工程①でVer.1.00、設計工程②でVer.1.10というように番号を振ることで、設計工程の進み具合を示すことが可能です。

同一設計工程内で更新

比較的短い期間で更新版を発行しなければならない場合に、末尾の数値を更新するケースがあります。例えば、設計工程①をVer.1.00で発行してから軽微な修正をし、Ver.1.01で再度発行するなど。発行後に後工程から質問を受けて修正する場合などが該当します。

Office文書の変更履歴機能をオンにする

変更履歴を記載するのと同時に、Office製品の変更履歴機能も活用すべきです。Wordの場合、この変更履歴機能が充実しています。この機能をオンにすると、変更を加えた箇所が自動で見え消し状態になり、色も変わります。さらに、いつ誰が編集したかも残るため、後で修正の経緯を辿ることが容易になります。ちなみに、見え消しとは、変更前の文章を残したまま取り消し線を上から引いて削除されていることを表現することを言います。ちょっとなじみのない言葉ですね。

変更履歴機能をオンにした後、変更履歴を「承認」するタイミングを決めるのが実は重要です。これを曖昧にしておくと、変更管理がめちゃめちゃになります。例えば、Ver.1.00からVer.2.00へバージョンが変わった際の変更履歴が残っている状態で、Ver.2.00からVer.3.00への変更履歴が混ざってしまうと、変更点の抽出が困難になってしまいます。そのため、このような事態を避けるための運用方法の1つの例を示します。

・後工程へ変更履歴付き版を展開する

　例）Ver.2.00で変更履歴オンを関係者へ展開

・開発文書修正作業に着手するタイミングで変更履歴を「承認」する

　例）Ver.2.00の変更履歴を「承認」し、Ver3.00を作成する

このように運用することで、Ver.1.00⇒Ver.2.00間の変更点と、Ver.2.00⇒Ver.3.00間の変更点を区別して管理することが可能となります。

開発文書を受け取った後工程では変更履歴をどのように認識し活用しているのか

開発文書を作成している技術者にとって、この変更履歴作成はとても面倒に感じます。

しかし、読み手に変更内容を適切に伝えないと思わぬトラブルを生みかねません。

例えば、以下のような場合、後工程の人はどのように変更点を認識すればよいでしょうか？

• 変更箇所の記載がない
• 文書内で明らかに変更がされているが、変更履歴に記載がない
• 変更箇所がALLとなっており、かつ、変更内容が抽象的な記載になっている（全体的に修正など）

上記のような状態だと、開発文書の新旧を並べて比較しないといけませんね。初めから変更履歴を作成していれば、後工程の作業にスムーズに入ることができます。

後工程の方が開発文書を受け取ると、要求分析という活動を行います。その際、ベースとなる開発文書からどのような変更点が生じているかを把握し、設計活動の工数を見積もります。そのため、後工程の方が適切に変更内容を追えるようにしておくことがとても大切です。例えば、以下のように変更点から設計文書への影響有無を確認し、工数を見積もることが想定されます。

まず、各変更点に対し、設計文書の変更が必要か否かを分析します。そして、どの設計文書への影響なのかを可視化します。それにより、変更点による設計への影響を可視化し管理することが可能となります。

開発文書を変更する頻度について

ご参考までに、開発文書はどの程度の頻度で変更されるのかについて触れておきます。自動車開発プロジェクトの場合、1つのプロジェクトで大体2年程度かかります。その間、何回か開発の区切りを置いて管理します。トヨタ社の場合、以下のような区切り方をします。

・AS（Advanced Stage）：量産開始の24カ月前
・FS (Final Stage) ：量産開始の18カ月前
・CV (Confirmation Vehicle)：量産開始の12カ月前
・1A（1次号試）：量産開始の6カ月前
・量確（MPT：Mass Production Trial）：量産開始の2カ月前
・品確（QCS：Quality Confirmation Stage）：量産開始の1カ月前
・量産開始（SOP；Start Of Production／LO；Line Off）

引用元：https://monoist.itmedia.co.jp/mn/articles/2006/22/news011_3.html

上記の区切り毎に、開発文書を発行するケースが多いです。CV仕様、1A仕様といった具合です。設計を行う後工程としては、この発行毎に仕様書に記載されている変更履歴を頼りに、設計書への影響分析を行うことになります。

まとめ

本記事では変更履歴の必要性や重要性、および記載する際のポイントについて解説しました。変更履歴を基に後工程で影響分析を行うため、変更履歴をわかりやすく作成することが重要です。また、その際、変更点に対し変更のカテゴリを設けることで、管理が容易になります。なお、変更の要因となった情報（質問票など）へのリンクをつけておくことで、変更の経緯を後で調べるのに役立ちますので、是非ご参考にしていただければと存じます。また、記事後半では変更履歴をどのように後工程で分析するのかについて触れました。変更履歴を作成する際、読み手の気持ちを意識して作成していただければ幸いです。最後に、参考情報として、自動車開発における開発フェーズおよび仕様発行頻度について触れました。本記事で触れたのはトヨタ社の事例ですが、他自動車開発でも類似の管理がされています。

関連記事