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

背景

開発プロジェクトでは、考えを文書化することが極めて重要です。

その中でも特に変更履歴の重要性は高いと言えます。

変更履歴は、開発者や利害関係者に過去の変更を理解する手助けをします。

本記事では、開発文書における変更履歴の役割と、効果的な書き方について解説します。

なお、本記事では、要求仕様書/機能仕様書/設計書/評価仕様書などを総称して開発文書と呼んでいます。

つまり、開発に関与する全ての文書のことです。

なお、必ずしもすべてのプロジェクトでこうなるとは限りませんので、1つの考え方であると解釈いただければと思います。

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

変更履歴は、開発文書において欠かせない要素です。

なぜならば、変更履歴がないと、以下のような問題が発生します。

変更履歴の記載ポイント

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

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

変更のカテゴリを明確にしておくことで、後工程の方が変更の内容を理解しやすくなり効率化に繋がります。

特に「追加」に関しては日程へのインパクトが懸念されるため、優先度高く内容を見ることになります。

「明確化」という言葉は聞きなれないかもしれませんが、仕様を定義する側にとっては便利な言葉です。

例えば、「修正でも追加でも削除でもないが、問い合わせがあったので誤解を招く表現を修正したい」というときに使います。

備考列を設けていますが、変更の要因となった情報を残すのに便利です。

例えば、例に記載したように管理番号を記入しておくことで、修正の意図や背景が後で追跡できるようになります。

備考に何を書くか、は議論が分かれるところではありますが、利害関係者間で予め合意しておくことを推奨します。

バージョンの付け方

変更履歴の記載ポイントで触れましたが、変更点と開発文書のバージョンを紐づけるべきです。

その際、バージョンの付け方に意味を持たせることも重要です。

例えば、以下のように数値の桁毎に意味を持たせることが多いです。

上位文書の発行毎に更新

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

上位文書であるシステム機能仕様書のバージョンが更新された場合に番号を更新します。

つまり、この桁ではソフトウェア開発の入力情報を管理していることになります。

ソフトウェア開発のベースラインを意味する重要な番号となります。

突然システムという言葉が出てきましたが、ソフトウェアとハードウェアを含む製品としての振る舞いを記述した文書という位置付けです。

設計工程毎に更新

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

同一設計工程内で更新

比較的短い期間で更新版を発行しなければならない場合に、末尾の数値を更新するケースがあります。

例えば、設計工程①をVer.1.00で発行してから軽微な修正をし、Ver.1.01で再度発行するなど。

発行後に後工程から質問を受けて修正する場合などが該当します。

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

変更履歴を記載するのと同時に、Office製品の変更履歴機能も活用すべきです。

Wordの場合、この変更履歴機能が充実しています。

この機能をオンにすると、変更を加えた箇所が自動で見え消し状態になり、色も変わります。

さらに、いつ誰が編集したかも残るため、後で修正の経緯を辿ることが容易になります。

ちなみに、見え消しとは、変更前の文章を残したまま取り消し線を上から引いて削除されていることを表現することを言います。

ちょっとなじみのない言葉ですね。

文章を追加すると、このように違う色で表現してくれます。

では要求を書き換えてみましょう。

このようにホゲホゲが見え消しになり、アゲアゲが追加されていることがわかります。

Office文書の変更履歴を承認するタイミング

変更履歴機能をオンにした後、変更履歴を「承認」するタイミングを決めるのが実は重要です。

変更履歴を「承認」するタイミングを曖昧にしておくと、変更管理がめちゃめちゃになります。

例えば、Ver.1.00からVer.2.00へバージョンが変わった際の変更履歴が残っている状態で、Ver.2.00からVer.3.00への変更履歴が混ざってしまうと、変更点の抽出が困難になってしまいます。

そのため、このような事態を避けるための運用方法の1つの例を示します。

例えば、開発文書Ver.2.00を後工程（関係者）へ展開したとします。

その後、とある事情で開発文書に修正が必要になった場合、一旦、開発文書内の変更履歴を「承認」します。

開発文書内に変更履歴がないことを確認した状態で開発文書を修正し、Ver.3.00として後工程（関係者）へ展開します。

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

変更履歴を承認すると、このように文字色が通常色になります。

こうすることで、この文書に対するこれからの修正内容をレビューすることが可能となります。

開発文書の読み手は「どこが変わったのか？」に着目して文書を読みますので、変更履歴の承認を忘れないようにしましょう。

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

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

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

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

上記のような状態だと、開発文書の新旧を並べて比較しないといけませんね。

初めから変更履歴を作成していれば、後工程の作業にスムーズに入ることができます。

後工程の方が開発文書を受け取ると、要求分析という活動を行います。

その際、ベースとなる開発文書からどのような変更点が生じているかを把握し、設計活動の工数を見積もります。

そのため、後工程の方が適切に変更内容を追えるようにしておくことがとても大切です。

例えば、以下のように変更点から設計文書への影響有無を確認し、工数を見積もることが想定されます。

まず、各変更点に対し、設計文書の変更が必要か否かを分析します。

そして、どの設計文書への影響なのかを可視化します。

それにより、変更点による設計への影響を可視化し管理することが可能となります。

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

ご参考までに、開発文書はどの程度の頻度で変更されるのかについて触れておきます。

自動車開発プロジェクトの場合、1つのプロジェクトで大体2年程度かかります。

その間、何回か開発の区切りを置いて管理します。トヨタ社の場合、以下のような区切り方をします。

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

上記の区切り毎に、開発文書を発行するケースが多いです。

CV仕様、1A仕様といった具合です。

設計を行う後工程としては、この発行毎に仕様書に記載されている変更履歴を頼りに、設計書への影響分析を行うことになります。

まとめ

本記事では変更履歴の必要性や重要性、および記載する際のポイントについて解説しました。

変更履歴を基に後工程で影響分析を行うため、変更履歴をわかりやすく作成することが重要です。

また、その際、変更点に対し変更のカテゴリを設けることで、管理が容易になります。

なお、変更の要因となった情報（質問票など）へのリンクをつけておくことで、変更の経緯を後で調べるのに役立ちますので、是非ご参考にしていただければと存じます。

また、記事後半では変更履歴をどのように後工程で分析するのかについて触れました。

変更履歴を作成する際、読み手の気持ちを意識して作成していただければ幸いです。

最後に、参考情報として、自動車開発における開発フェーズおよび仕様発行頻度について触れました。

本記事で触れたのはトヨタ社の事例ですが、他自動車開発でも類似の管理がされています。

以下、簡単ではありますが、変更履歴に関してのまとめです。

関連記事