かれこれ1年半ほどITシステムの運用に従事しているが、ドキュメントを綺麗に維持し続けることは本当に難しい。私の担当してるシステムはETLを中心にしていて、比較的定型化された処理をするシステムだが、それでさえドキュメントには間違いや漏れが大量にある。挙句、システムのことを調べるときは、毎回Githubのマスターブランチにあるプログラムを解読している。なぜ、ドキュメントは綺麗に保たれないのだろうか？

まず第一に、ドキュメントの更新に関わる人間の問題がある。
運用上、既存のプログラムに改修をしたタイミング、新しいプログラムを追加したタイミングで必ずドキュメントを更新するべきなのだが、プログラムをリリースしてとりあえず動くことを確認した段階で、いったん茶でも飲むか、という気持ちになるのが開発者の常である。茶には記憶力を増す効果があるというが、たいていの開発者は茶を入れているくらいの時間ですっかりドキュメントの更新など忘れてしまう。
本当に大事だと思っていることは後回しにしないから、開発者の気持ちとしてはドキュメントを軽んじているところは多少ある。動くものを作るという仕事には明確な価値があるように思えるが、それをドキュメントにするのは言ってみれば後片付けみたいなもので、（運用で困ったことがないと）価値がないように見えてしまう。

第二に、そもそものドキュメントに関する問題がある。
ドキュメントが、システムを記述するに十分な情報量を持っていないことがある。ドキュメントの形式は、最初にシステムが作られて、運用プロセスの開始時に設計されることがほとんどだと思うが、初期のプログラムには十分なフォーマットでも、それが5年10年たった時に十分な記述力を持ち続けることはほとんどないだろう。機能追加や、既存のコードの書き換えなどでシステムのほうが複雑化すると、それに合わせてドキュメントのフォーマットも変わるべきなのだが、実際にはドキュメントのフォーマットが更改されることはほとんどない。
また、多くのドキュメントはそもそも更新するのが面倒である。ある程度正規化されたドキュメントは複数にまたがるので、更新するべきドキュメントを洗い出すだけでもそれなりの知識が必要になる。複雑なシステムを記述しようとするとドキュメントもそれなりの記載項目の数があり、1項目ごとに内容をしっかりと把握しようとすると大変だ。だから、ドキュメントの更新は敬遠され、後回しにされる。

いったいどうすれば、ドキュメントとシステムの整合性を保ち続けることができるだろうか？

まず1つには、ドキュメントのフォーマットをシステムに適合したものに更新し続けることだ。そもそもシステムを記述できなければ、ドキュメントとしての意味が全くない。また、ドキュメントの設計においては、ある程度の正規化を行って、更新のルール(ドキュメントの粒度など)が明確になるようにするべきであろう。

そのような方法をとった場合は、必然的にドキュメントが複雑になってしまい、人に関する問題の増長を招いてしまうことはジレンマである。そこで、ドキュメントをできるだけ人間が更新しないようにするように、自動化することが必要だと考える。

やりかたの1つは、ドキュメントをシステムの中に埋め込んでしまうことである。ETLなどの比較的定型化された処理であれば、ドキュメントのなかの情報をプログラムで読んで走らせることが可能だろう。ただし、この方法を取ろうとしたら、完全にシステムのことを記述できるドキュメントを設計したうえで、既存のプログラムをすべて置き換える必要が発生する。また、ドキュメントのフォーマットに更新が必要な場合は、広範なリグレッションテストが必要になる。実行するのはなかなかにハードルが高い。やるとすると、マネージドサービスなどで品質が担保されたプラットフォームに乗っかるのがいいだろう。完全なドキュメントを作るのは難しいかもしれないが、汎用的な部分だけでもドキュメント化されるのは助かる（ETLで言うと、AWS Glueのデータカタログなどがよさそうである。）

もう1つの方法は、システムからドキュメントを作成することである。
つまり、動いているシステムやプログラムに対して、ドキュメント作成プログラムをかけてドキュメントを自動的に更新する。この方法は特に、例えばDB上のテーブルの設計情報のように、定型化されている処理やシステムに対しては有効である。ドキュメント自動更新は定型化されたものにしか使えないが、逆にいうと既存のプログラムの定型化・氾化を促進する可能性があるし、可読性を高めるためにも定型化・氾化はどんどん進めていくべきである。

以上の方法をとっても、どうしても自動化できないドキュメントがある。それは、なぜそのような設計なのか、なぜこのコードが必要なのか、などのシステムのメタ情報である。そして、そういう非構造的なメタ情報こそが最も重要である、と言っても過言ではない。定型化されていなくても、ある程度格納場所などをプロジェクトで決めておいて、ワードでもExcelでも何でもいので文章にして残しておかないといけないだろう。そういった情報はしばしば属人化されている。結局のところ、開発者や設計者にドキュメントの重要性を啓蒙することは避けて通れないのである。