つれづれなる技術屋日記

しがない技術屋。専門は情報工学で、「つれづれ技術屋」って呼んで。

変更履歴 直近は下?

このところ、とある勉強会でのドキュメントをいくつか確認している。会の複数の規則のドキュメント。

昨日あたり、読んでる時のイライラ度が結構ピークに。前から少し気になってたが、各ドキュメントの変更履歴が、降順というか直近が下の方。

  R1   2021/09/10 ○○ 第3条を削除 
  R1.1 2021/09/20 ○○ 第5条 ~しなければならない を ~しても良いに変更

みたいな記述。上の例だと2個だが、これが20年近くで数個とか、多ければ30個程度。規則自体が数個なので、関連性の確認、以前話題となった修正が行われたかの確認をやってると相当疲れてきてイライラ。

 

大昔のメカやハードウェアの図面では、隅っこにバージョンでの変更履歴書いたり、承認印を設けたりしてた。変更履歴は追加する格好なので、特に手書きの時代には、下の方に追加するのが普通だった。

図面が電子化されても、変更履歴欄は同様な運用が多かった気がする。当時は表での追加やコピー&ペーストが難しかったのが理由だろう。

直近を上に書くタイプと、直近を下に書くタイプとの対比は以下。

f:id:honda-jimusyo:20210925133713j:plain

大昔のソフトウェアドキュメントも手書き時代があったわけで、変更履歴に関しては直近を下にすることが行われていた。ただ、自分の場合、日本語ワープロとか、その後のパソコンでの文書ソフトの利用、そしてグループ内の合意もあって、直近を上の方にしてた。その方が、変更を実施したかの最初の確認に役立つ。バグレポートなり課題管理での記述と、ドキュメントへの反映の整合性の第1歩というわけだ。

 

そういう背景もあって、この変更管理の記述の件を、会に提起しようかなと考えてる状態。

ただしがあって昨今は、”差分”で、版での違いが細部までわかる。なので、手入力の変更記述よりも差分での情報の方が的確である。さらに言えば、大きな課題が、複数のドキュメント(規則)での整合性。特に、規則Aをこう変更するから規則Bをこう変更すると決めたのに、規則Aしか変更してない。そんな不整合が2,3ある。何年にもわたるドキュメントなので、当時の担当者がいないケースも。むしろそちらの方が課題で、俯瞰的な変更履歴というか変更管理をどうにかすべきとの意識が強くなってる。

 

10年、20年といったレンジで考えると、たかが変更履歴、されど変更履歴である。

 

©2005-2021 ほんだ事務所(honda-jimusyo) All rights reserved.