BLOGあります

■ドキュメントの分類

　中にはドキュメントを書くのが好きな人もいると思いますが、吉田はあまり好きではありません。一番の理由は面倒だからです。
　しかし、ドキュメントを残しておかないと困る局面は多々あります。まずはドキュメントの種類を分類してみます。

(1)設計ドキュメント

　ソフトウェアの設計に係わるドキュメントです。このドキュメントは実に多岐にわたり、要件定義からテスト仕様に至るまで、 実に多くのドキュメントがあります。特にソフト開発を生業としている場合には、ドキュメントがないと作業ができません。
　重要なドキュメントであることは確かですが、しばしばドキュメントとソフトウェアの実装の間にギャップが生じることがあります。例えば、 設計変更が入り、ドキュメントの修正を待たずにソフトを修正した場合など。もちろん、記録はありますが、 ひどい場合にはメモ書き1枚と言うこともあります。

(2)保守用ドキュメント

　設計ドキュメント以上に活用される機会が多いのが保守用のドキュメントです。保守とは、 ソフトウェアのバグフィクスや機能アップなど、実稼働後に生じた問題解決やメンテナンスの際に利用するものです。
　ソースコードに近いレベルのドキュメントは、自動作成する技術が確立されています。しかし、なぜそのような実装にしたかなど、 背景や意図については注意して管理する必要があります。

(3)取扱説明書

　ユーザーが触れるドキュメントです。「マニュアル読みますか？」でも触れましたが、この手のドキュメント作成が一番面倒です。 ユーザーに必要な情報を提供しなければならない上、実装と食い違うとユーザーからクレームが付きます。
　しかも、ユーザーにパソコン等に不慣れな人が多いほど、絵をふんだんに使う必要が出てきます。

■ドキュメント作成は憂鬱

　吉田が業務で行っているソフト開発の場合、会社の規定に従いファイリングします。シンプルぱっと２など個人的に作っているソフトは、 設計時ドキュメントを紙もしくはWikiに残します。紙の上で絵や図を用いてGUIを決定したり、データ項目、実装方法などを決定します。 Wikiには決定事項や、各種仕様を残しておきます。単機能のソフトについては、一切ドキュメントを残さないこともあります(この場合、 ソースコードがドキュメントの代わりになります)。

　物事にはインプットとアウトプットがあり、ソフトやドキュメントなどの成果物はアウトプットに分類されます。 ソフトウェアは複製が容易で、ハードウェア製品のように量産化の手順を仕様書にしなくてもコピーが作れます。そういう意味では、 アウトプットはソフトそのものと見ても良いと思います。

　理想はマニュアルを読まなくても使えるソフトウェアですが、ユーザー層が広がってくるとどうしてもより詳細な「取扱説明書」 が必要になります。しかし、この作業が非常に手間がかかるのです。
　特にソフトのリリースサイクルが短い場合は、ドキュメント修正までとても手が回りません。今のシンプルぱっと２の状態がまさにこれです。
　また、ソフトの修正内容にあわせて、既存のドキュメントを修正する必要がありますが、これも大変なのです。 文字だけで済む場合にはまだましですが、画像を手直しする必要がある場合には、泣きが入ります。

　企業が販売しているソフトで、バージョンアップがセキュリティホール対策、バグフィクスのレベルにとどまっている最大の理由は、 バージョンアップの予算が確保できないことですが、ソフトの機能追加等によるドキュメントの修正コストも考えてのことだと思います。

　一方、シンプルぱっと２のようなオンラインソフトは、市販ソフトならバージョンを上げて販売されるレベルの修正を行っても、 普通にバージョンアップ版としてリリースします。しかし、多くの場合、ドキュメント作成コストは含まれておらず、 修正箇所も限定されているケースが多いです。

　ユーザーの要望に応えてさまざまな機能追加に対応しようと思う反面、 それに伴うドキュメント修正の憂鬱さに嫌気が来ることがあります。いつかこの問題を解決できればと思いますが、 なかなかいい手は見つかりません。結果的にユーザーの手元には、実稼働バージョンと一致しないドキュメントが手元に残ります。