ソフトウェア開発にとってのドキュメントの重要性

ソフトウェア開発の現場において、既存のプロジェクトに後から参加するときや、久々に触れるシステムについて復習するときなど、まずはドキュメントを確認することがよくあります。ここで適切なドキュメントがあると、以下のようなメリットが得られます。

• アプリケーションの機能が追加された経緯、設計の背景の理解
  これらをコードとコメントだけで表現するのは難しいと思うので、親切な記述があると素早く理解できます。
• 暗黙知の明文化
  該当プロジェクトに参加した人だけが知っている経験的な知識や、成果物からはわかりにくい開発プロセスに関する知識は、ドキュメントに残さないと埋もれがちなので、まとめてあると重宝します。
• 失敗の共有
  意外に皆似たようなところでハマったり、ミスったりするものです。失敗についても恥ずかしがらずにまとめてあると、後の人が同じ作業をする時や同様の作業をする時に誤ってしまうことを避けやすくなります。

ドキュメントの陳腐化によって起きる問題

頻繁に更新されるプロジェクトや、久しぶりに関わるプロジェクトのドキュメントの場合、大抵は内容と執筆当時の状況とが大きく変わっており、古いドキュメントが役に立たなくなっていることがよくあります。
この対処にはついつい滞りがちな人間の手によるメンテナンスに代わって、ドキュメント生成(API設計書の自動生成など)やコード管理(インフラストラクチャのコード管理など)への集中といった自動的な対応を用いて

• コストの削減
• 直し忘れ防止
• レビューによる確認ミス軽減・精度の向上

を図るのが一つの解決策だと思いますが、全てのドキュメントに対してこれらを仕組み化するのは難しいと思うので、今回はそれら以外の方法について考えてみます。

現実的な方法

このようなドキュメントの陳腐化を防ぐためには継続的なメンテナンスが必要になりますが、多くのドキュメントがある場合に漏らさず行うのは非常にコストがかかります。一方、ドキュメントが少なければメンテナンスコストは低くすみます。極端な話まったくドキュメントが無ければ陳腐化の問題も起こりませんが、先述のメリットは一切得られないことになってしまいます。必要最小限のドキュメントを書き、保持することでメンテナンスコストを抑えつつ、陳腐化を軽減したいところです。
以下にそのための具体的な方法を挙げます。

プロジェクトごとにコアな少数のドキュメントを用意する

できる限り少数、可能なら1本のドキュメントに本当に重要な内容をまとめます。これだけはしっかりメンテナンスしていく必要があります。これ以外のドキュメントを一切書いてはいけないということではなく、コアなものを1本決めるということです。

無駄を省く

MMMの精神としてもドキュメント自体はどんどん書いていきたいので、その分内容には注意を払う必要があると思います。

• コード管理できる部分は最小限に抑える
• コードには含めづらい設計の経緯や実装の説明といった部分
• 図解を適切に用いて、文章量を減らす

など、書く時にじっくり確認しましょう。

ソースコードのコメントを手厚く

やっていることをできる限りコードそのものでわかりやすく表すのは重要なことです。しかし、コメントで説明することが適切な内容もたくさんあると思います。こうすることで、ドキュメントに任せる部分を適切に抑えます。

思い切って削除

大部分が古いものが残っていたら思い切って削除してしまっても良いかもしれません。

せめて印をつける

古くなっている記述に気づいたら、例えば「!!古い情報です。最新の状態は〜を実際に参照してください」とか、何かしら印をつけます。ある程度陳腐化を諦めるという感じです。少なくとも該当の箇所は古い内容だから、注意して読む必要があることは伝わります。

まとめ

現在を元に情報化したものが、時と共に陳腐化し、新しいものと乖離しがちになるのはソフトウェアに限ったことではなく、とても難しい問題だと思います。
ドキュメントが確かに有用である以上、陳腐化を無くすことはできないので上手に付き合っていく方法をこれからも試していきます。

参考URL

• エンジニア３大がっかりのひとつ　ドキュメントの陳腐化への対応
• 我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか
• 陳腐化と見える化
• ソフトウェア開発において、ドキュメントを陳腐化させないようにするためにどのような取り組みを行っていますか？

どいけん