01仕様書地獄の始まり ― エンジニアの日常とドキュメント作成あるある

キーワード: エンジニア あるある / 仕様書作成 / ドキュメントレビュー

コーヒーメーカー前の会話

エンジニアという生き物は、コードを書くために生まれてきたはずなのに、実際の仕事時間の半分近くは「文章を書くこと」に費やされている——これは入社三年目の芝浦悠人（しばうら・ゆうと）が、最近しみじみと実感している真理だった。

株式会社ノヴァテックの開発フロアは、朝十時を過ぎてもまだ半分近くの席が空いている。フレックス制なのをいいことに、みんな自分のペースで出社してくる。悠人は珍しく九時半に出社し、コーヒーメーカーの前で先輩の遠藤真央（えんどう・まお）と鉢合わせした。

「悠人くん、早いね」

「今日は例のドキュメント、遠藤さんにレビューしてもらう約束だったので」

「ああ、あれね」遠藤は目を細めた。彼女はチームで最も「文章にうるさい」ことで有名だった。コードレビューよりもドキュメントレビューの方が厳しいと、社内では半ば伝説になっている。

悠人が今取り組んでいるのは、新しく導入する社内APIの仕様書だった。リーダーの黒田さんから「他部署のエンジニアが読んでも迷わないように、丁寧にまとめておいて」と頼まれたのが二週間前のこと。悠人は張り切って、三日かけてドラフトを書き上げた。

そして今日、遠藤に初稿を見てもらう日だった。

先輩・遠藤真央のドキュメントレビュー四十七項目

会議室に移動すると、遠藤はノートPCを開き、悠人の書いたドキュメントを画面いっぱいに広げた。すでに大量のコメントが挿入されている。

「じゃあ、上から順にいくね」

「お、お願いします……」

悠人は覚悟を決めて椅子に座った。遠藤のレビューは伝説どおり、恐ろしく細かかった。

「まず、この『APIを叩く』って表現。社外向けにも流用する可能性があるから、『APIを呼び出す』に統一しよう」

「はい」

「このリクエスト例、末尾のカンマが余ってる。JSONとしては動くけど、コピペで使う人が混乱するから削除しておいて」

「はい……」

「あと、この『エラーが返る場合がある』って書き方、あいまいすぎる。どんな条件で、どんなステータスコードが返るのか、表にして」

「なるほど、たしかに」

「見出しのレベルがH2とH3で混在してる箇所がある。目次生成がおかしくなるから統一して」

「……はい」

会議室を出るとき、遠藤は最後にこう言った。

「細かいこと言ってごめんね。でも仕様書って、後から読む人のためのものだから。私がこれだけ言うのは、悠人くんの書いたものがちゃんと『育つ』見込みがあると思ってるからだよ」

その言葉に、悠人は妙に感動してしまった。よし、絶対に全部直そう、と心に誓った。

02完璧に直したはずが「誰にもレビューされてない」と言われた話

キーワード: レビュー 基準 / 仕様書レビュー / 職場あるある

指摘事項を一つも取りこぼさず反映した二日間

その日の午後から翌日の夜まで、悠人はほぼドキュメントの修正だけに時間を費やした。四十七項目の指摘を、一つも取りこぼさないように丁寧に反映していく。

用語集を作り、表現を統一し、リクエスト例のJSONは実際にパーサーに通して構文エラーがないか確認した。エラーコード一覧は表組みにし、色分けまでした。見出しレベルも整理し、目次も自動生成されるようにMarkdownの構造を組み直した。

作業を終えたとき、時刻は夜十一時を回っていた。画面に映る仕上がったドキュメントを見て、悠人は静かな達成感に包まれた。

「これはもう、隙がないぞ」

念のため、翌朝もう一度読み返し、誤字を二箇所見つけて直した。それから満を持して、Slackでリーダーの黒田さんにファイルを送った。

「黒田さん、API仕様書の初版ができました。遠藤さんに細かくレビューしてもらって、指摘は全部反映済みです。ご確認お願いします」

送信ボタンを押した瞬間、悠人は妙な高揚感を覚えた。まるで受験の答案を提出したときのような、あの独特の緊張と解放感だ。

リーダーからの衝撃の一言

返事が来たのは、その日の夕方だった。黒田さんが悠人のデスクにやってきて、ノートPCの画面を見せながらこう言った。

「悠人くん、これ見たんだけど……正直に言うと、誰にもレビューされてない文章みたいに見えるんだよね」

一瞬、何を言われたのか理解できなかった。

「え……あの、遠藤さんに四十七項目も指摘をもらって、全部直したんですが」

「うーん、そうなんだ。でも構成が頭に入ってこなくて。読んでいて『結局これは何のためのAPIなんだっけ』って何度も迷子になる。あと、専門用語の説明が足りなくて、他部署の人が読んだら詰まると思う」

悠人は頭が真っ白になった。四十七項目の指摘を一言一句反映したはずのドキュメントが、「誰にもレビューされてないみたい」と言われる。この世界に一体どんな理不尽が存在するのか。

「あの、遠藤さんには本当に細かく見てもらったんですけど……」

「うん、遠藤さんのレビューは間違ってないと思うよ。でも、彼女が見てるのは主に『文章としての精度』なんだよね。私が見てるのは『初めて読む人が迷わず理解できるか』っていう構成の話。別のレイヤーの話をしてるんだと思う」

黒田さんは悪気なく、あっさりとそう言った。悪気がないぶん、悠人の胸には妙な虚無感が広がった。

03レビューの基準は人それぞれ ― 職場あるあるな悩み相談

キーワード: 職場コメディ / SE 小説 / レビュー基準の違い

同期・三ツ矢との自販機トーク「道に迷う地図」

その夜、悠人は同期の三ツ矢（みつや）と社食の自販機コーナーでぼやいていた。

「四十七項目だよ、四十七項目。カンマの位置まで直したのに」

「うわ、それは徒労感すごいな」三ツ矢は缶コーヒーを開けながら苦笑した。「でも分かる気がする。レビューって『何を見るか』の基準が人によって全然違うんだよな。うちのチームなんて、リーダーによってPRの通し方が真逆だったりするし」

「そもそもさ、遠藤さんは間違ったこと言ってないんだよ。用語は統一されてるし、誤字もない。表現も丁寧になった。なのに『レビューされてないみたい』って言われるの、意味わかんなくない?」

「たぶんさ」三ツ矢は少し考えてから言った。「悠人が磨いたのは『文の精度』であって、『伝わる構成』じゃなかったんじゃない? 完璧な日本語で書かれた、道に迷う地図、みたいな」

「道に迷う地図って、なんだよそれ……的確すぎて腹立つ」

悠人はため息をついて、自販機のボタンを無意味に眺めた。炭酸飲料のボタンが、なぜか壊れかけの信号機のように点滅していた。

リーダーに直接聞いてわかった、レビューの本当の目的

翌日、悠人は思い切って黒田さんに時間をもらい、あらためて聞いてみることにした。

「黒田さん、率直に聞きたいんですけど、良いドキュメントの基準って何なんですか。遠藤さんの言うことを全部聞いたのに、黒田さんには全然違う評価をされて、正直混乱してます」

黒田さんは少し驚いたような顔をして、それから笑った。

「あ、それ聞いてくれて助かる。実は私、最初に頼んだときに伝えるべきことを伝えてなかったなって、あとで思ったんだよね」

「と、言いますと」

「私が欲しかったのは『他部署のエンジニアが、初見で迷わず使えるドキュメント』。だから本当は、書き始める前に『想定読者は誰で、その人はどれくらいの前提知識を持ってるか』をすり合わせるべきだった。そこを飛ばして『丁寧にまとめて』としか言わなかったのは、私の説明不足」

「……なるほど」

「遠藤さんは遠藤さんで、渡された文章を『正しい日本語、正しい構造』にする達人だから、そこを徹底的に磨いてくれる。それはそれですごく大事な工程。でも、それは『地図の文字が読みやすいかどうか』のチェックであって、『そもそもこの地図で目的地にたどり着けるか』のチェックとは別物なんだよね」

悠人は思わず唸った。

「三ツ矢の言ってた『道に迷う地図』、まさにそれだ……」

「誰の言葉?」

「同期です。的確すぎて悔しい発言をされました」

黒田さんは声を出して笑った。

04仕事で学んだドキュメントレビューの教訓、新人へ伝える

キーワード: 仕様書の書き方 / 新人エンジニア / レビューのコツ

三つの質問で変わった仕様書の書き方

その日から悠人は、ドキュメントを書く前に必ず「三つの質問」をするようになった。

一、想定読者は誰か。
二、その読者は何を知っていて、何を知らないか。
三、読み終えたときに、読者は何ができるようになっているべきか。

この三つを最初に確認してから書き始めると、驚くほど筆が迷わなくなった。構成の骨格が先に決まるので、細部の表現を磨く遠藤のレビューも、以前よりずっと効果的に機能するようになった。むしろ、骨格がしっかりしているぶん、遠藤の細かい指摘が「文章の完成度をさらに一段引き上げる仕上げ」として綺麗にハマるようになったのだ。

三週間後、悠人は改訂版のAPI仕様書を提出した。黒田さんの反応は、以前とは打って変わったものだった。

「これ、めちゃくちゃ読みやすい。他部署の人にも渡せそう」

「本当ですか」

「うん。しかも遠藤さんの細かいチェックも入ってるから、文章としての精度も高い。二人のいいとこ取りって感じ」

悠人は思わずガッツポーズをしそうになったが、隣の席の遠藤に見られていることに気づいて、なんとか堪えた。遠藤は画面越しにこちらを見て、にやりと笑った。

「悠人くん、成長したね」

「遠藤さんのレビューのおかげです、本当に」

「いやいや、あなたが黒田さんにちゃんと聞きに行ったからでしょ。私は聞かれたことにしか答えられないからね」

その言葉は、悠人の胸にじんわりと染み込んだ。レビューというのは、結局のところ「聞かれたことに答える」行為なのだ。だとしたら、良い答えを引き出すために大事なのは、良い質問をすることなのかもしれない。

半年後、新人指導係になった悠人が伝えたこと

半年後、悠人は新入社員の指導係を任されることになった。初めての一対一ミーティングで、彼はこう切り出した。

「ドキュメントを書くときはね、いきなり書き始めちゃダメだよ。まず三つ質問することを覚えて」

「三つの質問、ですか」

「想定読者は誰か。その人は何を知らないか。読んだあと何ができるようになっているべきか。この三つ」

新入社員は真剣な顔でメモを取った。悠人はふと、あの夜の自分——四十七項目の指摘を一言一句反映して、達成感に浸っていた自分を思い出し、少し照れくさくなった。

「あと、レビューしてくれた人が『何を見ているか』を意識するのも大事。文章の精度を見てる人もいれば、構成の分かりやすさを見てる人もいる。両方大事だから、どっちの意見も無下にしちゃダメだよ」

「先輩、なんか含蓄ありますね」

「痛い目見て学んだからね」

悠人は苦笑いしながら、自分のデスクに戻った。画面には、今まさにレビュー待ちの新しいドキュメントが表示されている。送信する前に、悠人は小さく独り言をつぶやいた。

「想定読者は誰か。読者は何を知らないか。読んだあと、何ができるようになっているべきか」

呪文のようなその三つの問いを唱えてから、悠人はレビュー依頼のボタンを押した。今度こそ、道に迷わない地図が書けているはずだと、静かに信じながら。

—完—