ワードサラダ記念日
よく、（申し訳ないんだけど）ジュニアな人のPull Request(PR)の説明とかで、やったことの内容がワードサラダみたいになっていることがある。 曰く: - 目的 - 変えたこと - 変更したファイル - やった内容 - 追加したテスト みたいな... ところでPRの説明をなんで頑張るかっていうと、人間（将来はAI）に、そもそも自分が何をしたくて、実際に何をしたかということを **伝える** ためである。 伝えることが目的なので、伝わっていない場合価値を生み出していないと言える。 伝えることのテクニックについては大量に書籍もあるので適宜読んで欲しいが。少なくとも、いくら頑張ってワードサラダを作り出してもあまり意味がない。あるいは、受け取り側に負担を押し付けていてずいぶん非生産的なように思える。 つまり、人は意味が構造化されているものでないと簡単に理解することができないという点を伝えたい。 - * - -* - ここまでワードサラダはダメと言ってきたが、一方で、ワードサラダは伝えるコンテンツの第一歩でもある。 ワードサラダの場合、個々の単語の間に繋がりが見えないので、読む側としては丸暗記の項目が並んでるのかな？ みたいな印象を与え、何かを伝えるのは難しい。 一方で、個々のワードサラダのelementには本当に伝えたい「事実」が転がっている感じになるのかなと思うので、その「事実」に論理的なつながりを作ってあげればいい。よく起承転結とか序破急とか言っているやつで、PRなら、たとえば僕がこの場で適当に考えただけでもこういう構造が考えられる: - なぜ、このPRを作ったのか？ -- 何が問題で、何を変えたいか - そのために何をしたのか？ -- 〜という実装を変更した -- その変更は〜というファイルがある - その変更を確実なものとするために何をしたのか？ -- 〜という実装についてXXという自動テストを追加した -- 手動で〜が動作することを確認した - 読む人に、何をして欲しいのか？ -- 変更内容を把握して、変えていいか自体に意見が欲しい -- 変更内容が正しいか確認してほしい 一例に過ぎないが、よくあるPRテンプレートのようになったのではないだろうか？ テンプレートを作るのはそういうこと、事実のワードサラダを構造に落とし込む手助けということである。 また、これは単に箇条書きをするという話でもない。箇条書きの作る構造が文章の構造に自然に一致していないとあまり意味がない。場合によって、箇条書きを作ってもう一回構造を見直したりする必要があるだろう（というか、構造を直しやすいというのが箇条書きのメリット）。 なんというか、読む人の疑問点に寄り添うような形で、まず〜を知りたい、〜を知ったら次はXXが知りたいだろう、というふうに相手の立場をシミュレートするイメージで作るといいかと思う。 最後に全体を見直して、作られた論理的なつながりが自分の言いたいことと概ね合致しているか確認するのも大事。
なお、この文章もわざと散文的に書いてるので読みづらい、受け取り側に負担を押し付けていくスタイルです。