やる気がストロングZERO

やる気のストロングスタイル

システムドキュメントの管理方法のベストプラクティスを考える

システムドキュメントの管理って地味に難しい。
そもそもドキュメントが無かったり、どこにあるのか分からなかったり、あっても情報が古かったり、複数の場所や形式に分散していたりしていて、いざという時に全然使えないような状態になってしまってたりする。
そこで、これらの問題が起こりにくいドキュメント管理方法を考えてみた。

システムドキュメントはシステムのgitリポジトリで管理する

上記の問題のほとんどはシステムとドキュメントに位置的な距離があるから発生している。
システムとドキュメントに距離があるとどうしてもドキュメントの更新が忘れられがちになる。
ドキュメントがシステムと同じgitリポジトリにあると、コードの変更と共にドキュメントも整合性を合わせておく行動に繋がりやすいし、変更が漏れてしまってもコードレビュー時に指摘を受ける事になりやすい。

また、言わずもがなgitで管理される事でシステムのバージョンごとのドキュメントを確認できるメリットもある。

AsciiDocで記述する

gitで管理するは良いが、単なるtextでは表現力が足りない。
テーブル表現や画像の貼り付けなども必要になる。
このあたりあまり詳しくないので、表現力とpreviewのしやすさがあれば何でもいいと思うのだが、AsciiDocが良いのではないかと思った。 AsciiDocはElasticSearchのドキュメントで使われていて、浸透度は低いが表現力や閲覧しやすさの点で良いのではないかと思っている。
というか、ElasticSearchのコードを読んでいて、このドキュメント管理方法を知り「これがベストプラクティスなのではないか」と思ったのであった。

文書ファイルで管理する運用のデメリット:オリジナルがどれか分からなくなる

wordのような文書ファイルで管理する場合、コピーが作成される可能性がある。
コピーされるだけなら良いが、下手するとコピーとコピー元がそれぞれ独自に更新されていって「同じようだが異なる同名のドキュメント」のようなややこしいものが出来てしまったりする。
「ある機能について調べたけど記載がなかった、と思ったら別の場所に存在する同名ファイルには記載があった」みたいなことが起きる可能性がある。

外部サービスで管理する運用のデメリット:永続性に懸念がある

google ドキュメントや、githubwikiなど、外部のwebサービスにドキュメントを記載すると便利だったりするのだが、ずっと使い続けられるかどうかに懸念がある。
会社の都合(予算とかセキュリティポリシーの影響とか)で使えなくなる可能性もあるし、サービス自体の変化(サービス内容の変化とか終了とか)にもさらされる。
もっとよい別のサービスが現れるかもしれない。
こういった理由でドキュメントを別サービスへ載せ替える時、同様機能が提供されていなければ一部情報が抜け落ちてしまったりするし、載せ替え作業が中途半端になれば「この情報はAサービスに、その情報はBサービスに記載されている」のような状態になる。

ドキュメント保守は実装作業よりも工数を取るのが難しく後回しにされがちで、こういった状況に陥りやすい。

上記のような理由でドキュメントが複数に分散すると、情報を探して見つからなかった時「探せなかっただけでどこかにある」のか「情報そのものがない」のかの判断がしにくい。
無いものをいつまでも探したりする。

また、外部サービスに書いていると検索機能も外部サービスに依存してしまう。サービスの検索機能が糞だと情報が存在しても見つけられない、みたいなことも発生する。

まとめ

システムドキュメントはシステムと同じgitリポジトリでAsciiDocで記述するのが良い。