読み手に配慮した技術文書って何だろう
システム開発における、設計書や手順書などのドキュメント類。僕が書いたドキュメントは概ね「分かりやすい」と評価される一方、上長からは「もう少し読み手を意識して書くと良いかも」と忠告を受ける。
…読み手を意識した結果がこのドキュメントであって、その狙いはうまく行っていることが今分かったんだよなぁ。
一般的に、「技術文書は誰にでも分かりやすく書くべし」というのはよく聞くと思う。それもそうなんだが、限度というモノがある。「AWS コンソールにログインして、S3 のバケット一覧画面を開いて…」というこの一文で理解できない人に、果たして理解してもらう必要があるのだろうか？
この案件に未経験の新人が入ってきて、既存メンバと同等のタスクをこなすことはない。この案件に参画するメンバ自体がそもそも殆どいない性質のモノだ。このドキュメントを分かれば良い人というのは、既存メンバの、実際に手を動かす人だけでいいのだ。
上司には AWS のアカウントが発行されているが、半年経っても一度もログインすらしていないのは初期パスワードを変更していないことで分かる。この上司が、ドキュメントを読んで、中身を作業者と同じ程度に理解できる必要は果たしてどこにあるのだろうか？「S3 って何 GB のハードディスクなの？」などとトンチンカンなことを言っている上司が理解できるレベルにまで細かく書くコストを、どうして払わなければならないのだ？そのコストを掛ける必要があるの、あなただけなんですけど。
要するに、上司、あなたはこのドキュメントの対象読者ではないのだ。「S3 のバケット一覧を開いて」の一言で理解が出来ない程度の学習レベルの人は、あえて、そもそも対象読者として想定していないのだ。
「ブラウザというのはですねぇ、このアイコンをダブルクリックして開くモノでして…」「JavaScript っていうのは Java とは違いまして…」なんて、毎度書いていられん。お前はよそで勉強して、この文章で理解できるようになってから話しかけてこい。そういうことだ。
「誰にでも分かる設計書」「誰にでも分かるテスト仕様書」を巡って、こんなトラブルがあったのを思い出した。
1年目の新人に、テストを任せたことがある。設計書、実装、テスト仕様書の作成は済んでいて、チームメンバがかなり細かく書いていたので、新人は読んだとおりにテストを実施すれば良いだけだった。実際、新人はほとんど質問することなく、テスト自体は正確にこなし、テスト証跡もキッチリ残せていた。だが、見る人が見れば、それは複数の不具合が検出されているテスト証跡だった。
何が起きていたか。
1つ目のテストは、作成したシステムのログイン画面からログインして、ユーザトップ画面が表示される、というモノ。確かに「ユーザトップ画面」の画面設計書どおりのレイアウトで画面が表示されているスクショが撮れていた。しかし、ブラウザのステータスバーには JavaScript の構文エラーを示す警告マークが表示されていることも、スクショから読み取れた。
つまり、画面の初期表示処理にバグがあり、JavaScript が正常に動作していない可能性が高いことが分かる。それは、とあるモーダルを「閉じる」処理がうまくいかないというバグだったのだが、その新人が任されたテスト対象範囲ではなかった。新人本人のやるべきこととしては、「ユーザトップ画面が表示されること」をしっかり確認したワケだ。しかし、多少でもフロントエンドが分かる人が見ていれば、関連する機能のバグに早期に気付けた可能性があった、といえる。
また、新人が任された別のテストでは、「生年月日の入力欄で、フォーカスアウトすると月・日の値が2桁にゼロパディングされること」というテストがあった。つまり「1 月」とユーザが入力した場合は、「01 月」と自動置換してほしい、そういうシステムだったワケだが、新人は「ゼロパディング」の意味が分からず、置換処理がうまく動いていない「1 月」という表示結果を見て OK と判断してしまっていた。
いずれも、「誰にでも分かる仕様書になっていなかったから、抜け漏れがあったのだ」と、言えなくもない。「開発者コンソールに JavaScript エラーがないこと」と書くとか、「1 と入力したあとにフォーカスアウトしたら 01 と表示が切り替わること」と具体的に書くとか、そういった工夫ができなかったかといえば、できたかもしれない。
だが、このレベルのことを毎度書かないと伝わらないような相手も見越して文章を書くというのは、相当な手間と時間がかかるし、正解も終わりも見えないモノである。僕はこの新人の「確認漏れ」や「意味を知らずに取り違えた」といった結果は、仕方ないモノだと思うのだが、その会社では「不具合の検出漏れだ」として、改善策の提示を命じられて面倒臭かった覚えがある。
僕としては、この新人のミスは悪くないのだが、色々仕事をやってきた結果、「そういう大事なことは、大事なポイントが分かっている人にやらせる方が良い」と思うようになってきた。そしてそのためには、「この書きぶりなら新人にもお願いできるかな」と思わせるような、一見平易な文章というのはリスクも伴う、という考えに至った。
そんなこともあり、僕が書く技術文書は、対象読者をあえて狭めた書き方をしている。kubectl コマンドを打つための KubeConfig の用意の仕方は毎度説明しないし、「ISO 8601 形式」と書けば通じるような相手しか見据えていない文章を、あえて書いている。そうやって読者をふるいにかけているのだ。
その程度の知識を持っている人が読めば、間違いなく理解して実行できるように書いている。その程度の知識もない人には、よく分からない文章になるように書いている。なぜなら、雰囲気でコマンドをコピペ実行されると重要なリソースを削除されかねない作業手順書だからである。慎重に理解して実行しないと正しいコマンドにならないので、素人がよく読まずにコピペするとエラーメッセージが出るだけで何も実行されない、というドキュメントに、わざとしているのである。
「あなたのための文章じゃないです」という意図が伝わったか伝わっていないか、恐らく伝わっていないのだろうが、上司としては「よく分からないところがあるなぁ」と思ったのだろう、僕に「もっと読み手に配慮した文章を」と忠告をしてきたワケだが、「素人はそういうこと言ってくるだろうなー」と思いながら書いた文章でそう言われたので、僕は狙いどおりだと思ったワケである。
皆は「分かりやすさ」って何だと思いますか。「誰にでも分かる文章」って何だと思いますか。それは、その場において、どのくらい必要なことでしょうか。
