ドキュメントが必要なわけ

ドキュメントは、ソフトウェアの世界では、唯一の目に見える成果物である。ソフトウェア開発では、ドキュメントを通してしか、ソフトウェアを可視化できない。ドキュメントが、貧弱なものしかないと、残るは難解なソースコードだけになってしまう。ドキュメントからしか、作成状況を目で確認できないからこそ、ソフトウェア開発は難しいとされている。

だが、エンジニアは、ドキュメントなんかは信じていない。信じられるのは、ソースコードだけだと皆が言う。それは、世の中にあるドキュメントは、全て貧弱でうそが書いてある（アップデートされていない）からである。そこで、エンジニアは、ドキュメントの正当性を確かめるためにも、ソース解析を始める。これは、よほどのロス作業である。開発後の確認であれば、ソースがあるからよいが、開発途中のサブシステム間の連携の場合は、ドキュメントが全てになってしまう。

ドキュメントとは、ソフトウェアを人間が分かる形に具現化したものである。それだけ大事なものであることを、よく理解し、頭の中にしまいこんでいるロジックを、吐き出して共有すべきである。エンジニアは、ドキュメントの作成を嫌がる傾向がある。それは、目に見えないものを創出する作業が、難しいことを意味する。だが、頭の中で構築したロジックは、不完全なものが多い。一度目で見て確認することにより、格段の向上が見られる。リーダーは、ドキュメント作成作業が、業務の負荷にならないように、無駄な生成物を除外し、真に必要なものだけを判断し、スケジューリングにも作成とアップデートの時間を考慮すべきである。

Framework を導入すると、往々にして管理ドキュメントが、増える傾向にあるようだ。エンジニアに対する負荷が高くなり、多すぎるドキュメントは、真に必要なドキュメントを埋もれさせ、ドキュメントの品質を落とし、ドキュメントに対する信頼を落としかねない。Framework を導入する際は、管理のためのドキュメントに偏らないように、開発のためのドキュメントを最優先に考えるべきである。

vol.48

成果としてドキュメントの量が評価対象なんて笑い話もありますが、ドキュメントは大局的にみるためのツールでソースコードはその具体的な実現手法がかかれたものです。視点や表現する内容が異なりますがどちらも同期していることによってソフトウェア的「着眼大局、着手小局」が実現できます。ですが人が行うとどちらかに偏ってしまいがちです。つじつまを合わせるために四苦八苦するよりもMDDなどのツールの力を利用していくことも大事ではないかと思います。