後日談をひとつ

http://d.hatena.ne.jp/tmpfile/20040501#p1 の

誤解を生む表現への結果

あるソフトウエアの機能を説明しているマニュアルや技術文書等に『Aが更新されると Bが Cを自動的に更新します』と書いてあると、まるで「Bが Aの更新を瞬時に検知して Cを直ぐに更新します」といったような印象を受けますが、実際は「Aが更新されている事は Bは知りません。Bは定期的に Aが更新されたかどうかを Dを参照して調べます。Bは Dを参照した時に Cを更新すべきと判断したら Cを更新します。」というオチだったりします。

定期的ってのは、例えば E分おきだったりします。Aが更新されても最大E分は Cが更新されない時間が存在します。しかも Cを更新するのは判断するのだから Fという条件付だったりする。Dとか Fってなんなのよという疑問も生じるでしょうし、そもそも A、B、C、D、E、Fは一体何なのかという理解も必要になってくるでしょう。

良くあるのが「Aが更新されると自動的に Cが更新されるって書いてあるから、Bがすぐ Cを更新すると思うじゃねーかっ(怒)」という批判。

私はマニュアル作った人でも、その製品を作った人でもありません。その製品の調査依頼は受ける立場であり、説明してくれと言われたら答えを出さなければいけない人。

結果としては、色々言いたい事はあっても「マニュアルは不適切な表現です」って、ひたすら頭下げます。相手が目の前にいようがいまいが。調査の上、理解して、説明してね。但し調査方法はナイショ。この調査方法の部分で稼いでる、今の私の技術者としての仕事上の任務とでも言うべきか。

の続き。ちなみにこのソフトウエアはいわゆる受託開発系のソフトウエアでは無く、(例えば amazon.comあたりで)パッケージ・ソフトウエアとして販売されているものをイメージして頂ければと思います。そのソフトウエア等のサポートの話です。

マニュアルに『Aが更新されると Bが Cを自動的に更新します』と書かれていた機能は今はどうなったか。
新しいバージョンで Bがなくなりました。そして Aが更新された時に Cを自動的に更新する機能が実装され、それが簡単な設定により出来るようになったため、E分おきという概念自体は無くす事もできれば、無くなった Bと同じように動作するモジュールを(これまた)個別に設定して実行できる(：新たにプログラムを作らなくても良い)ようにもなっています。
実は、数年前からこの新機能の実装そのものの要望は出されていたのを知っていて、アーキテクトがどのような仕様にするか決定していなかったのも知っていたので、私はマニュアルの修正は要望しませんでした。新しいバージョンでどうなるのかも、わからなかったし。
ここまでは、お客様から見える結果としては、前の話と同じ。もしかしたら新しいバージョンの検討段階で変わった事に混乱する状況が予想されます。

その先で何をしたかですが。
このようなマニュアルの記述では誤解を生みやすいので説明を間違えないようにするための文書を残し、少なくともサポート依頼を受けたら誰でも同じように説明ができる状態にしておきました。この文書が何の役に立つかですが、同じ事を説明するのに人によって差がある事が防げ、何より再調査する必要は無くなります。但し、ここまでも改善結果としては見えない。

次に、(新しいバージョンが出てからの行動でしたが、) この新機能との旧バージョンの機能差異を説明をする文書がどこにも存在しなかったので、文書を作って(お客様の目に付きやすい Webサイトへ)技術情報として公開する事にしました。
今のところ、この技術情報は誰でも無償で参照できるような公開はされていません。誰かがこの情報に気付いて、引用や応用して無償で参照できるような公開をするのとほぼ同じ情報に育ってくれる事を期待しています。