自然な日本語より、 意図どおり伝わる日本語

Tamachi.sre#7
https://tamachi-sre.connpass.com/event/408227/

Transcript

1. Tamachi.sre #7 1st Anniversary LT Special ⾃然な⽇本語より、 意図どおり伝わる⽇本語 2026/11/11 Tamachi.sre #7 @kohbis
2. 「意味は分かるでしょ」で公開した⽂章は、誰が読むのか • コードを書くとき … テストとレビューで「期待どおり動作する」ことを確認してからマージす る • ⽂章を書くとき … 書いた本⼈が読み返して「意味が分かるか」で公開する その⽂章を読むのは • 障害対応中の別チームのメンバー、夜中の当番、半年後の⾃分や誰か、そしてAI • 聞き返せる相⼿がいないときほど、⾔い回しひとつで読み⼿の⾏動が変わる 「⾃然な⽇本語」にするお話ではなく「意図どおり伝わる⽇本語」のお話 （このLTのなかに技術要素はまったくありません！） 2
3. SREが書く⽂章は、読み⼿がほぼ⾃分ではない • • • ⼿順書 … 障害対応中の別チームの⼈が読む アラートメッセージ … 夜中の当番が読む ポストモーテム … 半年後の誰かが読む 👇 聞き返して補えるうちは問題にないが、、、 👇 障害対応中は聞き返す相⼿がいない。半年後は書いた本⼈がもういないこともある → 書いた意図と、読まれた解釈の差分 ＝ 情報のパケロス ポストモーテムの原因に 「ドキュメント、⼿順書、レビュー観点の記述があいまいだった、不⾜していた」 と書いたことがある⼈は、⼀度はこのパケロスを観測している 3
4. 「誰にとっての」読みやすさ？ 事実「ファイルのアップロードに失敗したら3回まで再試⾏する」 ⽂書 読み⼿ 知りたいこと 書くこと README 初めて開いた開発者 何をするか、どう動かすか 再試⾏があること、回数の設定場所 コードコメント 半年後に変更する⼈ なぜこうなっているか 3回にした理由、変更すると何が起きるか 運⽤⼿順書 障害対応中の⼈ 今何をするか、どう確認する か 再試⾏が尽きたときの症状、確認コマンド、次 にやること サポートページ （toC） 困っている利⽤者 ⾃分は何をすればいいか 「時間をおいて再度お試しください」。再試⾏ という語は出さない サポートページ （toB） 取引先の担当者 ⾃社の運⽤への影響 回数と間隔、失敗が確定する条件、問い合わせ 先 同じ⽂を5か所にコピーすると、どの読み⼿にも過不⾜が⽣じる サポートページひとつでも、toCかtoBかで必要な情報が変わる → 「読み⼿は何のために読むか」「⾃分は何を伝えたいか」を先に決めると、書くべきことはおのず と決まるはず 4
5. 実例① エンジニアの⼝語は、書いた本⼈にしか⼀意に読めない ⼿順書やアラートメッセージでよく⾒る語 Before 解釈が分かれる点 After（⼀例） ジョブが⾛る 起動した？実⾏中？完了した？ ジョブが実⾏中である メモリを⾷う 使⽤量が多い？増えつづける？ メモリ使⽤量が増えつづける アラートを拾う 検知する？対応する？ アラートを検知して担当に通知する メトリクスに乗らない 対象外？記録に失敗？ メトリクスが記録されていない 「拾う」が検知なのか対応なのかで、障害対応中の⾏動が変わる 「乗らない」が対象外なのか記録失敗なのかで、原因の切り分けが変わる → 書き⼿には意味がひとつでも、読み⼿は複数の解釈ができてしまう 5
6. 実例② その⾏だけでは「何」や「誰」が分からない Before 読み⼿が困ること After（⼀例） 負荷が上がっていた CPU？メモリ？接続数？ディスクI/O？半 年後に同じ症状か照合できない DBの接続数が上限に達していた 毎朝実⾏されている 障害中に誰に聞けばいいか分からない 〇〇チームが毎朝実⾏している （前の⾏を受けて）ならないも のが対象 Slackで1⾏だけ抜粋されると意味が分から なくなる 消しても動作が変わらない記述が対 象 共通するのは、書き⼿の頭のなかにはある情報が⽂章に表現されていないこと • もちろん、1⾏に押し込めばよいわけではない • 読んだ⼈に意図どおりの意味で、できるだけ簡潔に伝わるかたちにする → そのために、その⽂章で何を伝えたいのかを先に考える 6
7. あいまいさを補ってくれる読み⼿ばかりではない 同じ⼿順書をAIにも読ませている • バージョンアップや定期メンテナンスでは、AIが⼿順書を読んで進め、⼈間は確認だけ ⼈間は前後の⽂脈であいまいさを補える（補ってしまう） AIはあいまいなまま別の解釈で実⾏する（しかも速い） → ⼈間が読んで⼀意な⽂はAIにも⼀意。AI向けに書き分ける必要はない （⾃分の場合） • • 気になる観点を書き出してAIに推敲させている 表記や⾔いかえの参考に、『記者ハンドブック』（共同通信社）も使っている 7
8. （まとめ）⾃然な⽇本語より、意図どおり伝わる⽇本語 ⽇本語を推敲するスキルやツールはたくさんある。どれも⽂を「⾃然」にしてくれる しかし「⾃然さ」と「想定する読み⼿に意図どおり伝わるか」は別の話 • 伝わるかどうかは、辞書にもスキルにも書かれていない • 「何のために読むか」「何を伝えたいか」の両⽅から、どう書くのが適切かを考えるしかない 明⽇からできること • 書く前に、読み⼿と伝えたいことを思い浮かべる • 書いたあとに、その⾏だけで意味が通るかを読み返す • レビューで、コードと同じように⽇本語の解釈が⼀意かを⾒る 書きなおす作業は、AIに任せてもツールを使っても、どちらでもよい その前に少しだけ「伝えたいことが伝わる⽇本語になっているか？」を考えてみるとよいかも？ 8