そのドキュメント、他の人にわかるの？
こんにちは、手塚規雄です。
日常的にあるわけではないのですが、本当にたまーーーーに思うことがあるのでコラムにしました。
その表記方法、コボラーしからわからないと思うよ
とあるドキュメントにてこんな表記がありました。
桁数：9(4) COMP
これは16進数の4桁の数字を表す2バイトだね！なんて分かる人は少ないと思います。多分。私はCOBOLができるので普通に読めるから良いのですが、職場で読める人は少数派でした。
何が言いたいかというとドキュメントなのに読み手に意図が伝わらないドキュメントなんて意味がないという事です。社内のドキュメントならまだ許せるのですが、先程の記載がされたドキュメントは一応、某大手メーカーさんから頂いた仕様書に記載されていた内容でした。社外の人間に見せるドキュメントにはもっと伝わる言葉を使わないとわからないという事です。その会社ではCOBOL表記は伝わると思ったのでしょうけど、COBOLが読める人は世の中では少数派というのは考えられなかったのか疑問です。
書き方を変えるのは誰でも出来るけど、できない理由、変えない理由がある
この手のドキュメントは本来、修正するのはそんなに難しいとは思いません。また作成者も修正したいと思っている人が多いかもしれません。でも変更できない、訳の分からない理由があります。その内の１つが作成者は良かれと思って修正したくても、承認者がそう思わない事が多いためです。
・昔もこうだったから、これからもこうやるべき（←思考停止）
・いきなり変更したら、見る人が困る（←今のほうが困っているのが現実）
・だまって言うことを聞いたどおりにやれ（←自分がいつも正しいという思い込み）
・この修正について、他の人から文句を言われたくない（←面倒くさい）
このように、あげていけばきりが無いほど、この手の愚痴とともにドキュメントの修正が承認されない理由が出てくると思います。
わかりやすい表現というのは結構難しい
ただ実際、わかりやすいドキュメントを作るのは結構難しいし、作るのにも時間がかかってしまう事が多いです。特に社外に出すドキュメントは自分たちにはそれなりに読みやすいと思っていても、どうしても社内の独自文化のルールで書いてしまう事が多くなってしまうのが現実です。そのため社外の人が読むとどうしてもわかりにくくなってしまいます。
完璧なドキュメントなどない、けどそこに近づけるようにする努力はすべき
完璧なドキュメント作成など目指したら、それこそドキュメント作成だけで終わってしまうし、そんなものは存在しないし、それでは意味がありません。でも読み手ができるだけ理解できるようにドキュメント作成することは大事です。
多くの人に理解されるような表現、それがどういうものかはわかりません。でも様々な職場を経験することで、今までの表現がローカルだったのか？それともどこでも伝わる表現なのか？を知ることができます。
だからこそ一つの職場で閉じこもるより、多くの職場を経験したほうが良いと思っています。これはドキュメント作成に限らず、技術的なことも含めてです。他にも社外の人と知り合うことで、職場ローカルな事だったのかも知ることができます。
なんにせよ、COBOL的表記が行われるドキュメントはこの世から無くなってほしいものです。
------------------------------------------------------------------------------
コメント欄やTwitter(@noriwo_t)にて書いて欲しいコラムの題材をいつでも受け付けております。ただしその内容に応えられるかどうかはわかりません。基本的にコメント欄には私自身がコメントしないのですが、題材リクエストに関してはレスをすることもありますので、よろしくお願いします。
コメントやTwitterでなく直接お話ししたいという希望の方にはスカイプ相談を受け付けています。もし興味があればこちらのURLからお願いします。