Slack や GitHub など、何かとテキストコミュニケーションを行う場面は多いのだが、自分なりに気をつけていることを書いてみたい。
まず、前提として自分は文字を読むのが嫌いだ。昔から本が嫌いで読むのが遅く、国語の成績はずっと低かった。流石に小中高の時よりはマシになっていて技術書などはまあ読むのだが、それでも得意になったわけではなく、できることなら１文字でも少なく読みたい。そして、自分がそこに認知負荷を感じるがゆえに、他人に読ませるテキストには気を遣う。なるべくシンプルかつ簡潔に要点を伝えるためにアンチパターン（と思うもの）を避けている。
以下では、個人的に気をつけている認知負荷を下げるための具体的な工夫を挙げていく。（認知負荷にも色々あるが、ここでは「読むのが疲れる」くらいの意味だと思ってほしい。）
「読んでおいて」...リンクの丸投げを避ける
ちょいちょい見かける「これを読んでおいてください」とリンクだけ共有するパターン。大抵の場合リンク先は長文のドキュメントだったり、ページ数の多いスライドだったりする。これが結構しんどい。どういう気持ちで読めばいいか分からないからだ。
その人が何を伝えたくてそのリンクを共有したかが分かっているだけで、だいぶ読みやすくなる。たとえば「セキュリティ対策をして欲しい」とか「競合製品がリリースされたので自社が危機的な状況である」とか。言われなければ自分に関係がない世間話かと思って読み飛ばすかもしれない。
リンク先をどういう気持ちで読んで欲しいかを書く。簡単なサマリも書く。
「この件」...踏むまで分からない指示語のリンクを避ける
これも一つ上と似ている話。プレビューでタイトルでも書いてあれば別だが、「この件ですが...」を見ただけでは分からない場合があり、確認のための１クリックが必要になる。
改善するには「API の件ですが...」とか「API に破壊的な変更があり対応が必要な件ですが...」などと、リンクに内容を含める。どこまで丁寧に書くべきかは状況によるので、「API の件」だけで自明ならそれだけで済ます。
結論を先に書く
これは言われ尽くされていることだが、背景などから順を追って説明しようとすると言いたいことがどんどん後ろに移動してしまう。以下は良くない例。（内容は真面目に読まなくて良い。他の例も同様）
@channel 先日このようなことがありました。その日はイベントの前日で準備が忙しく〜（中略） オフィスに入ってすぐに気づいたのですが〜（中略） その後、管理会社から電話があり〜（中略） 最終的に問題がないことは分かったのですが、危うくセキュリティ事故につながるところでした。 最後にオフィスを出る人は戸締りを忘れずにお願いします。
これだと何が言いたいのか分からないので読んでいて疲れるし、最後まで読む前に離脱してしまう。「【注意喚起】最後にオフィスを出る人は戸締りを忘れずにお願いします！」と伝えたいことを最初に持ってきて、詳細を後に続けると良い。詳細が長くなる場合は Slack のスレッドに続けても良い。
長いスレッドに呼ぶ時は内容を要約する
Slack で議論しているとスレッドがやたら長くなることがある。100 個のメッセージを経た後、その議論に参加していない他の人の意見を聞かないといけないことが分かり、「@xxxxx この件どうですか？」とメンション。呼ばれた人は 100 個のメッセージ全てに目を通す羽目になる。大体そういう時はストレートに話が進んでいないので、 60 個目くらいに「すみません！確認したところ今までの議論は前提がそもそも間違っていました！」みたいなメッセージがが挟まっていたりするし、「いや草」みたいなノイズでしかないメッセージも混じっている。
そもそも何の議論をしていて今は何が問題になっているのかを簡単に説明したい。いわゆる今北産業である。
箇条書きだけで伝えるのを避ける
こちらはなんでも箇条書きにして伝えようとするパターン。
「この件どうしましょう」
* 状況
* デプロイ作業中
* 担当者: A
* 16:30 頃
* staging 環境
* 事象
* DB マイグレーションに失敗
* エラー内容： DBError: カラム foo が存在しません
* 影響範囲
* X モジュール
* 解決策
* 問題の箇所だけをスキップしてデプロイ
* 多分問題はない
* 根本的な解決になっていない
* 明日デプロイし直す
* X モジュールに詳しい Y さんが本日不在のため
箇条書きで整理すると気持ち良いのだが、情報がフラットすぎたり、項目間の繋がりが見えにくくなったりする。書いている時は脳内で助詞や接続詞を補って読んでいるので上手く整理できていると思い込んでしまっているが、後で読み返すと「何が言いたいんだっけ？」となったりする。この例は Slack の会話だが、ドキュメントに書く場合も同様。
詳細を箇条書きにするにしても、先に伝えたいことは文章で書いた方がわかりやすい。この場合なら「staging デプロイ中にマイグレーションが失敗しているんですが、明日デプロイやりなおした方がいいですかね？一応スキップしてデプロイは出来るんですけど、今日は Y さんがいないので安全か不安です。」などと書く。文章にした分だけ冗長さが増しているようにも感じるが、箇条書きよりも意図を読み取る負荷は減っているように思う。
AI の回答を丸投げするのを避ける
「例の件ですが、 ChatGPT に聞いたら以下のように答えてくれました！」
とても良い着眼点です。 A の方法を採用するのは、多くの場合理にかなっています。しかしご指摘のように一つ懸念点を挙げるとすれば... （中略） ## 🚀 解決策 1: B の方法を採用する（最も手軽で確実） 今回の用途では B で十分です。この方法であれば、唯一の懸念点も払拭できます。 メリット * ~~~~ * ~~~~ * ~~~~ ### 実装例 （略） ## 🛠️ 解決策 2: A を採用しつつ、万一の場合にも備える（リスクは減るが工数増） もちろん A の方法でも実現可能です。しかし問題が起こる可能性は残るので、万一に備えた対策も必要でしょう。 メリット * ~~~~ * ~~~~ デメリット * ~~~~ ### 実装例 （略） ## ✅ どの案を採用すべきか（簡単なチェックポイント） 1. B を採用可能か -> 解決策 1 2. B を採用できない場合 a. 運用上のリスクが十分小さい -> 解決策 2 b. リスクがそこそこある -> 解決策 2 と 3 のハイブリッド ## まとめ （略）
AI の回答は冗長だ。こちらの前提を理解していないので「省略できるところは省略する」判断ができずに隙のない回答をしてくる。そこは人間が無駄なところは省いて伝えるべき相手に合わせた形に整理しないといけない。
これに似た話で、最近は AI が議事録を取ってくれるがやっぱりそのままでは使いにくい。ないよりはマシだが、現状では人間の取った議事録に及ぶクオリティになっていないので「読んで理解しておいて」とは言いにくい。
Pull Request の description を AI に書かせない（または簡潔に書かせる）
こちらも放っておくと AI はどこまでも冗長な description を生成する。毎回モジュールの依存関係とかを図示してきたりするし、コードを見れば分かることも懇切丁寧に説明していて、シンプルに読むのが大変。真面目に読まなくていいのかもしれないが。
そもそも同じ開発チームのメンバーならタイトルを見ただけで「あれね」と分かるので、 description がそもそも不要な場合が多い。その場合は何も書かない（チケットへのリンク程度）ので、レビュアーは何も読まなくて済む。他に書いたとしても、大抵は数行の概要＋参考リンク＋スクショくらいで、たまに注意点とか重要な判断が入った場合に長く説明する程度。
なので基本的に AI に説明は書かせないのだが、定型作業の場合は「このフォーマットで書いてね」と指示すると便利なこともある。もちろん、指定するフォーマットはシンプル・簡潔なものだ。
過度なテンプレート化を避ける
次のようなドキュメントのテンプレートが用意されていることがある。
# {タイトル}
## 概要
<!-- ここに概要を書く -->
## 背景
<!-- ここに背景を書く -->
## 詳細
<!-- ここに詳細を書く -->
## 注意点
<!-- 注意点があれば書く -->
## 参考リンク
<!-- 参考になる資料があればここに書く -->
テンプレートがあることによって書くことを迷わなくて済むし、内容の抜け漏れも防ぐことができる。そこまではいいのだが、冗長さによるデメリットがメリットを上回ってしまうことがある。ほとんどの項目が空で済む場合、読み手は退屈な項目名の羅列を眺め、その中から本当に埋められている項目を探さなければならない。テンプレートによっては「不要な項目は消して良い」と書いてある場合があるが、消すのも面倒なのでそのまま残している人が多数派だと思う。
冗長なテンプレートが生まれる理由はいくつかある。よくあるのが、何か不具合が起きた時に「どうしたら考慮漏れを防げたのか」という議論になり、「仕組みで解決」する方法の一つとして採用される「テンプレートへの項目の追加」だ。有効な手段であり、大成功した例も知っているので悪いことではない。が、経験の浅いメンバーがごく基本的なことを考慮できなかったという理由で項目を追加すると、経験を積んだ人にとっては分かりきっていることをわざわざ書くことになる。同様に、読み手への配慮を怠る人に対する強制力としてテンプレート化を推進する場合もある。普段から配慮できる人はテンプレートなどなくても参考資料へのリンクを貼ったりするのだが。テンプレート化に限らず、組織施策を一番低いレベルに合わせてやるとどんどん面倒臭くなっていく。組織に面倒さを導入しないためには個人の「気を付ける」努力も必要だったりする（任せるだけでなく気を付けるためのハックを共有すると効果的）。
選択肢に番号を振る
これは読む量を減らすのではなく、議論をスムーズに運ぶための方法だ。以下を見比べてほしい。
* 先に基盤を整えてから全チームに展開する * 基盤の整備とチームへの展開を並行して行う * まず１チームで試して上手くいったら基盤に昇格させる * 基盤は作らず各チームで独立して管理する
1. 先に基盤を整えてから全チームに展開する 2. 基盤の整備とチームへの展開を並行して行う 3. まず１チームで試して上手くいったら基盤に昇格させる 4. 基盤は作らず各チームで独立して管理する
後者の方が圧倒的に議論がやりやすい。「３で行こう」「いや４じゃね？」のように言えるので。注意点としては、逆に「３ってなんだっけ？」のようになってしまったこともあるので、常に選択肢は見えるところに置いておきたい。
図解する
もはや説明の余地もないが、多くの場合有効な方法である。
注意点としては、あまり独創的な図を描いてしまうと描き手のメンタルモデルと読み手のメンタルモデルが一致せず、逆に理解が困難になる可能性があることだ。アプリケーション層は上か下か、矢印が表すのは依存の向きかデータの流れか、それら一つ一つが描き手の中で一番理解しやすい方法で表現されているのでついつい「こうなってて〜」と説明してしまいがちだ。しかし、まずは読み手が描き手のメンタルモデルに追いつくまで丁寧に説明する必要がある。基本的にはシーケンス図やフローチャートなどありふれたものを使うのが良い。
また、認知特性は人によるので絵よりも文字や音声の方が理解しやすい人もいることにも注意が必要だ。自分はなんでも絵で理解するので図解を多用するのだが、苦しんでいる人もいるかもしれない。
ここで説明しなかったもの
この記事では「認知負荷を下げる」ことにフォーカスしたため、より一般的な「分かりやすい文章を書く」ことには触れなかった。自分は文章のプロではないので、そういうのは探せばもっと良い書籍がいくらでもある。この記事には「とにかく文字を読むのが面倒くさい」ということだけを書いた。（そして最近「面倒くさいって言い過ぎ」というフィードバックを受けた。）
