『読み手につたわる文章 - テクニカルライティング』を読んだ

技術書典で購入した『読み手につたわる文章 - テクニカルライティング』を読んだので学びになったトピックについて書く。

1.2 「知らない」と書けない（P14）⌗

そして自分が対象物を思っていたより「知らない」ということに、我々は気付いていないことが多いのです。上手な絵は、対象物のことを知らないと描けません。それと同じように、分かりやすい実用文は、文章力のあるなし以前に 対象物をよく知らないと書けない のです。

文字にすると当たり前のことのように感じるが、ブログを書いているとよく実感する。

技術的な内容であれば、当然対象を理解していないと書けないし、自分の考えでさえもいざ言語化しようと思うとなかなか筆が進まないことが多い。

そうした場合にはまず自分が何を言いたいのかを整理して理解するようにしている。

2.1.4 いつまでに何をしてほしいのか書こう（P25）⌗

何の食べ物だか言わずにいきなり「食べて! ほら食べて!」とスプーンを差し出されると、「え、怖い。なになになに?」となって、とても素直に口を開く気にはなれませんし、食べたところで猜疑心で味もよく分かりません。そんなときは「初めて作ったプリンが思いのほか美味しくできたので一口食べて感想を教えてほしい」というように、どういう意図で読み手に何をして欲しいと思っているのかを先に説明してあげる必要があります。

引用部分の前に書かれていた例示のエピソードがわかりすぎて無限に頷いてしまった。認知負荷が高い文章を読むにはエネルギーを要する。

報告なのでただ把握だけしておいて欲しいのか相談がしたいので意見を求めているのかなど、読み手に求めるアクションを明示すると読み手の認知負荷が低くて良さそう。

結局伝えたいことが伝わらないことには意味がないので書いて満足、ではなくドキュメントを書くことの目的を見失わないようにしていきたい。

2.2 文書構造や文章量が適切だと分かりやすい⌗

2.2.1 大枠から始めてだんだん細かくしていこう（P26）⌗

文章で何かを説明するときには、先に大枠を理解してもらい、それから段々細かい 内容にしていくという順番を意識しましょう。

以前上司にレビューで指摘してもらって以来意識するようになった。

コンテキストを共有していない人とコミュニケーションを取る時は特に重要だと感じている。自分と相手が持っている情報の差分を埋めるように情報を提示できるとスムーズにコミュニケーションを取れる印象がある。

2.2.3 既知から未知に繋ごう（P28）⌗

文章を書くとき、「大枠から詳細へ」の他に意識すべきもう1つの順番は「既知から未知へ」です。 技術ドキュメントを読んでいても、最初から知らない単語や知らない概念ばかりが次から次へと出てくると、「知らないことについて説明してくれているけど、その説明がまず分からない」という状態になります。

あまり意識したことがなかった。

一度にまとまった情報量を記述したい時にはこのあたりまで意識して書くと認知負荷が減ってよさそう。

2.4 再利用しやすい文章にする⌗

2.4.2 並列はナカグロ（・）で書かない（P34）⌗

文章の中で並列を表そうとして「ホーム・検索・マイページ・ヘルプのタブは非表示にできません」のようにナカグロ(・)を使っていると、再利用されて箇条書きになったときに、次のような見た目になることがあります。

着せかえの設定時、以下の機能は非表示にしたり、見た目を変更したりできません。
・ホーム・検索・マイページ・ヘルプのタブ
・トレンドワード機能
・ID連携機能

対策として、最初から箇条書きにしておくか、読点を使うといいとのこと。

いつもどう書くか迷っていたが・で並列関係を表現すると上記のデメリットがあるので読点を使うようにしてみようと思う。

2.4.4 リンクテキストを「こちら」にしない（P35）⌗

リンク切れになったときやテキストだけコピーされたときにリンク先がどこを指しているのかわからなくなるため、以下のようにどういったページなのかも含めて書くのがいいとのこと。

また「詳しくはShops APIのAPIリファレンス をご覧ください」

また、読み手としてもリンクを踏む前にどんなページへ飛ばされるのかわかるというメリットも紹介されていた。

まとめ⌗

具体的な知見が理由とセットで書いてあってとても勉強になった。¹チームで仕事をする上で認知負荷を下げる工夫の重要性を日々感じるのでこれから意識的に実践していきたい。

紹介したトピック以外にもたくさんの知見が紹介されていたので気になった方はこちらからぜひ購入してみてください。 こちら ²