行間の説明ばかりしているエンジニアに先はないねー

この3連休には庭の高木の枝を払いたいんだけれどどうも天気が不安定で昨日はできず、今日も午後は雷雨の予報なのでダメっぽいなぁ。枝を払わないと芝が陰になってしまっているから。あと自分でも不思議なことに毎年植えてはイマイチの家庭菜園は真面目に手入れをしてるから育成が順調のように見える。支柱を経ててねじる針金で誘引したり、脇芽を取り除いたり、陰になる葉や枯れそうな葉を除いたりやることをやっているだけど、週一とはいえ見ないといけないものは見ないといけないんだという証左なんだなぁ、なんて。

おかしな話と言えばおかしな話で進捗をモニタリングする必要性を一番わかっているのは自分なのにね。ではなんで以前は植えた後に手を抜いて放置していてたものが今年は煩雑に足を向けるのかな、と思い巡らしても何も心当たりがないんだけど、内心では「1回くらいはちゃんとやってみよう。」と思っているのかもしれない。どれにしても日差しの強い日は麦わら帽子をかぶり、長靴を履き、長袖のシャツを着て。そうそう、去年までと違うのが2つあって、一つがちゃんと長靴を履くようにしたこと。もう一つは朝露に濡れてもいいようにと蚊に刺されにくいように長そでを切るようにしていること。

蚊に刺されれると痒いのがどうも嫌だし、ムヒを塗ってもあまり効いた気がしないんだけど50度の温水で刺されたところを掛け流すと不思議と痒みが止まるとためしてガッテンでやっていたことを思い出してやってみたら本当に痒みが取れて以後そればっかり。

なんでも試してみないと効果ってわからない。というか、多分サンダルで出て行ってそのあとの始末＝足を洗う手間や蚊に刺されて痒くなることが煩雑に足を向けることを遠ざけていた真因だったのかも。因果関係を解き明かせばこの2つが必ず出てきそう。

キミの説明は行間ばっかり
レビューをしていると、レビューを受けるドキュメントはエンジニアの経験で精度が上がるというか「てにをは」のような基礎的なところが経験で担保されるかと言えばそう行かないのが不思議なところです。

「てにをは」は棚に上げるくらいもっとひどいのは、何をしたいのか良くわからなかったり、突然子細な記述か始まるような文書を書いて持ってくるケースです。まぁ、一番ダメなのはレビューの時間に持ってくるケースですけどね。例え差し替えるとしても、レビューアに事前に初稿を出さないのはいけません。理解しようとする気が失せるから。

本人にとっては「何がわからないの」かわからない
何をしたいのか理解に苦しむドキュメントや子細な記述から始まる文書を書いている本人にとってはそのドキュメントを書いている内容で充分なわけです。で、その後内部レビューをしているとしても内部なので背景を知っている。だから、暗黙の内に高いコンテキストの中でレビューをしています。その内部レビューを受けたレベルでドキュメントのライフサイクルが回るならそれでもいいんです。ドキュメントとしては。エンジニアとしてはそんなドキュメントしか書けないなら他で食べていけませんけど。

でも、そのドキュメントが外部の人に渡るなら、ワタシのような第三者のレビューアが読むことが想定されるなら、そんなのダメだし、内部レビューで指摘しないといけないです。

そうしたドキュメントのレビューをしていると、当然ワタシは訊ねるんですよね。だってわからないもの。

これは何をするの。
誰がするの。
何をいつまでにするの。
何を作るの。
それをするのに前提としていることは。
それで何が制限を受けるの。

単純に5W2H1Gで書いてくれればいんだけど。端的に言うと、ゴールだけ書いてある。子細な手順と。

こちらとしては、書かれていることを「理解したいから」そう書くことになった経緯を聴くことになるんですよ。「なんで。」って。だから酷いとドラマの事情聴取のようになってくる。いや、自供させるわけではないか。でもやっていることは一緒だもの。本人が頭で考えているけど、

「ドキュメントに書かれていない行間」

を聴かなければならないんだもの。それを聴けないならレビューは中止せざる得ない。組織の中の第三者的なワタシがわからない文書が顧客がわかるかどうかって話です。例え顧客がわかったとしてもそれは当事者同士だけの話でコトが揉めたら一巻の終わり。第三者に分からないんだから仲裁しようがないもの。

じゃあどうしたらいいのよ
そんなこと、人に聞かないで自助努力してくださいな。たくさん本も出ていますよ。いえいえ、教えてくださいな、と言われちゃうとオジサン頑張っちゃおうかな。いや。

そのドキュメントの初めに背景を書いちゃいえばいいじゃないですか。経緯があるならそれを箇条書きにとか、行間にあることを。ドキュメントの文書に書かれていない自分の頭の中で自動補完していることが書かないといけないことです。それを書いてください。