watermint.org

今度はドキュメントに関する話題です。佐藤さんのブログによると、ドキュメントは不要、最小限に。とのことで、これは同じくそう思います。というか、そうあってほしいと願っていますが、なかなかそういう訳にも行きません。

佐藤さんは今回のブログ・エントリでは触れられていませんが、 今後の潮流としては開発の現場にも内部統制がはいってくるということがこのドキュメントを残すという、エンジニアのあまりやりたがらない作業を法令等によって強いられることになります。

今回、佐藤さんはドキュメントの役割は「人に伝えること」 をドキュメントの主な使命とされていますが、内部統制という視点から見れば「監査あるいは内部統制の証拠」としての使命を負うことになります。内部統制がどの程度開発の現場にはいってくるのかは不勉強のため今はわかりませんが、少なくとも開発から本番への移行は必ず別の担当者が行わなければならないとか、そういったルールがはいってくるでしょうし、勘定系や基幹系のシステムであればそのシステム仕様書と実装に矛盾が無いかなどの監査を受けることになるかもしれません。

ところで近年、開発の現場ではウォータフォールの反省あるいは、様々な開発支援ツールを導入することによって積極的にドキュメントを作成する工数を減らそうという動きがありました。たとえばJavaであればそのAPI仕様をソースコード中に記述し、javadocという形式のドキュメントが自動生成できるようになりました。また、JavaのソースコードからUML表現を相互に同期をとれるような、たとえばNetBeans Enterprise Packとか、ツールも安価あるいは無償で手に入るようになりました。

また、あるいはその逆にWordやExcelで作ったドキュメントをもとにJavaソースコードや設定ファイルを生成するようなソフトウエア、たとえばキヤノンソフトウエアのWeb Performerなど、も数多く存在するようになりました。

この二つのアプローチは「ドキュメントを作成する」という工数を確実に自動／半自動化することを可能にしました。 佐藤さんの言うような「実装者の意思を設計者に伝える」という種類のものは前者の「プログラムからドキュメントを生成」というアプローチ、また「顧客の意思を設計者に伝える」という種類の物は後者の「ドキュメントからプログラムを生成」というタイプのアプローチによって自動／半自動化することが可能になってきました。

ところが、たしかにこのような潮流によって主としてメンテナンスしなければならないドキュメントが減ってくれることを期待していましたが、現実をみれば実際には重複した内容のドキュメント、冗長あるいは不必要なドキュメントは未だに氾濫しており、ドキュメントを作成し、探し出し、利用するための工数は実質的ほとんど減っていません。

この問題の原因と考えているのはドキュメントがどういう目的で、誰に読ませようとしているのかが不明瞭である状態のまま作成され続けているというところです。この傾向は知る限り日本においては顕著です(せいぜい英語がぎりぎり読めるぐらいなのでそれほど多くの国の事情を知っている訳ではありませんが・・・)。

たとえば日本でよく見かけるドキュメントの「はじめに」の章は形式的な挨拶が書かれている程度でそれ自体無くても不都合のない場合がほとんどです。このため、たとえば対象読者をプロジェクト全員に広げてしまい、実際に読むのはJavaに詳しいエンジニアであるのにも関わらずJavaの基礎を延々と説いているというような無意味なドキュメントが作成されてしまっています。一方、欧米のドキュメントでは最初の章に「ドキュメントの利用目的」「ドキュメントの対象読者」「ドキュメントの前提としている事柄」といったことが記述されており、それに続く内容も整合性がとれた物になっています。

そういった意味で、実際のところ開発プロセス云々の前にドキュメントの作り方自体が間違っていると言わざるを得ないと思っています。ぜひとも、開発プロセス云々の前に「理科系の作文技術」でも読んでもらいたいと思うシーン幾度か経験したことがあります。