- Authors
- Name
- Youngju Kim
- @fjvbn20031
- なぜこれが昇進より先に来るのか
- 文章は組織の中で何をするのか
- 設計文書 — 残るのは捨てた案です
- 障害報告 — 事実と解釈を分ける
- レビューコメント — 等級を付けると衝突が減ります
- 文章が安くなるとき値が上がるもの
- 手を動かす
- 続けて読む
- 参考資料
なぜこれが昇進より先に来るのか
エンジニアに文章力が大事だという助言は、たいていこう終わります。うまく書ければ評価で認められる、と。間違ってはいませんが、順序が逆さまです。
順序を正すとこうなります。文章はまず自分の思考を検証する装置です。次に、組織の中で反論できる面を作る道具です。そしてその二つの結果として評価に影響します。三番目だけを見て近づくと文書が宣伝物になり、宣伝物は組織で素早く割り引かれます。
一番目が核心です。説明できない設計はたいてい理解できていない設計です。頭の中では滑らかだったものが、文にした瞬間に空白を露わにします。だから書くことは、表現の能力である前に自分の理解に対する検査です。
文章は組織の中で何をするのか
三つのことをします。
一つは非同期の拡大です。会議は参加人数だけ時間が掛け算されますが、文書は読む人が増えても著者の時間を増やしません。十人が一時間会議すれば十時間、同じ内容を文書にすれば著者が二時間、九人がそれぞれ十五分です。
もう一つは時間移動です。文書は三年後の人に話しかけます。そのとき知りたいのは何が作られたかではなく、なぜそう作られたかです。
三つめが最も重要です。文章は反論できる面を作ります。口で言った主張は、反論するにはその場で即座に反応せねばならず、たいてい声の大きいほうが勝ちます。紙に書かれた主張は各自が時間をかけて検討でき、反対意見をまとめて持ってこられます。良い文書は自分の主張を通す道具ではなく、自分の主張が誤っていたときにそれを早く知る道具です。
設計文書 — 残るのは捨てた案です
設計文書は時間が経てば大半が古びます。構成図は変わり、インターフェースは違うものになり、日程は合いません。三年後も価値が残る部分はほぼ一つだけです。捨てた案と捨てた理由です。
理由は第3回で扱ったものと同じです。コードは採用された案だけを見せ、代案は見せません。だから後から来た人が「これ、こうすればいいだけでは」と言うことが繰り返され、その方式はたいていすでに検討され捨てられたものです。
そして必ず表示すべきものがもう一つあります。取り消せない決定です。データ形式、外部に公開するインターフェース、ストレージの選択のように、後で変える費用が急に大きくなる項目は、文書の中で目立つように分けるべきです。この表示があればレビュアーはどこに時間を使うかが分かり、なければ取り消せるものについての議論でレビュー時間が尽きます。
障害報告 — 事実と解釈を分ける
障害報告で最もよくある失敗は、一つの文の中で事実と解釈が混ざることです。「キャッシュ設定が誤っていたせいで障害になった」という文には観測された事実と因果の主張がくっついており、くっついていると両方とも検証されません。
分けるとこうなります。事実は時刻順にだけ書きます。何時何分にどの通知が来て、何が確認され、何をして、いつ回復したか。解釈は別の節で行い、それぞれの解釈にどの事実が根拠かを添えます。こうすれば、読む人が解釈に同意しなくても事実は共有できます。
これに付く原則が、非難せずに書くことです。GoogleのSRE本はこれを、関わった全員が善意を持ち、その時点で持っていた情報のもとで正しいことをしたと前提することだと説明します。そして理由を道徳ではなく実用として示します。非難のある雰囲気では問題が表に出ず覆い隠され、覆い隠されれば組織の抱えるリスクが大きくなる、というものです。同じ章は、人は直せないがシステムと手順は直せる、という一文でこの原則をまとめています。
これは礼儀の問題ではなく情報収集の問題です。非難が予想される報告では、人は自分のしたことを正確に語らず、正確でない事実の上にはどんな改善も設計できません。
レビューコメント — 等級を付けると衝突が減ります
レビューで摩擦が生じる大きな原因は、コメントの重みが伝わらないことです。書いた人はすべてのコメントを要求として受け取り、レビュアーは軽い提案のつもりでいます。
解決は単純です。コメントごとに等級を付けることです。
例 — コメントの前に付ける三つの表示
[ブロック] この状態でマージすると問題が出ます。根拠: 同時リクエストで残高が負になります
[提案] ここはこうすると読みやすいと思います。変えなくてもマージ可能です
[好み] 私なら違う書き方をしますが、正誤の問題ではありません
この表示一つでレビュー時間が大きく減ります。書いた人は何に先に答えるべきかが分かり、好みのコメントでマージが遅れることがなくなります。
内容の側にも規則が一つあります。要求ではなく観察と根拠を書くことです。「これを変えてください」より「同時リクエストが二つ来るとここで残高が負になりそうですが、合っていますか」のほうが良い。後者はレビュアーが誤っている可能性を開いており、開いておくと実際に誤っていたとき会話が早く終わります。
文章が安くなるとき値が上がるもの
ここは正直であるべき部分です。文を作り出す仕事は目に見えて安くなりました。だから「よく書けた文書」の希少性は以前と同じではありません。
では何が残るのか。二つに見えます。一つは何を書くかを決める判断です。この決定で取り消せないものは何か、どの代案が本当の競争相手だったか、どの事実をまだ知らないかを知ることは、文を生産することとは別の能力です。もう一つは署名です。文書に名前を掛け、その決定の結果を引き受けるのが誰かは委譲されません。
ただしこの部分は確信を持って言いにくい。組織が文書をどう扱うか、署名の重みが実際にどう変わるかは、まだ定まっていない領域です。今言えるのは、文の生産が安くなったのは確かで、その文が含む判断の検証は安くなっていない、という程度です。
手を動かす
今週、自分が最近下した技術的決定を一つ選び、それについて三段落だけ書いてみてください。採用した案、検討して捨てた代案二つと捨てた理由、そしてこの決定で戻しにくい部分。A4半ページで十分で、これを書くのに三十分以上かかるなら、その決定はまだ整理されていません。
- 思考力トレーニング — 問題を自分の言葉で書き直すことが最初の手として入っています。設計文書の最初の段落がする仕事とまったく同じです。
通じない場合も書いておきます。決定権者が文書を読まない組織では、長い文書は何もしません。そういう場所では文書を会議の五分前に読める一枚の要約へ圧縮し、長い版は後から来る人のための記録としてだけ残すほうがよい。
続けて読む
- このブログの関連記事: 文章で説得する — 設計文書とRFCが通る構造
高いまま残る技術シリーズ
参考資料
- Postmortem Culture — Google SRE Book — 非難せずに書かれた報告は、関わった全員が善意を持ちその時点の情報で正しいことをしたと前提するという定義、非難の雰囲気が問題を覆い隠すという論拠、人は直せないがシステムと手順は直せるという一文がここから来ています。2026-08-15閲覧。
- コメントの等級表示と設計文書の優先順位の整理は上記資料にあるものではなく、この記事でまとめた方式です。