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

Makefile

@@ -22,4 +22,8 @@ compress-to-webp:
 
 .PHONY: lint
 lint:
-	npx textlint --fix  ./content/posts/**/*.md
+	npx textlint ./content/posts/**/*.md
+
+.PHONY: lint-fix
+lint-fix:
+	npx textlint --fix ./content/posts/**/*.md

content/posts/ichiban-yasashii-agile-no-kyouhon/index.md

@@ -1,7 +1,7 @@
 ---
 title: "『いちばんやさしいアジャイル開発の教本』 を読んだ"
-tags: ["読書メモ", "アジャイル"]
-keywords: ["読書メモ", "アジャイル"]
+tags: ["読書ログ", "アジャイル"]
+keywords: ["読書ログ", "アジャイル"]
 
 cover: "https://blog.kyu08.com/cover.png"
 description: ""

content/posts/technical-writing-book/index.md

@@ -0,0 +1,100 @@
+---
+title: "『読み手につたわる文章 - テクニカルライティング』を読んだ"
+tags: ["読書ログ"]
+keywords: ["読書ログ"]
+
+cover: "https://blog.kyu08.com/cover.png"
+description: ""
+date: 2024-06-03T00:21:05+09:00
+author: "kyu08"
+authorTwitter: "kyu08_"
+draft: false
+showFullContent: false
+readingTime: true
+hideComments: false
+color: ""
+---
+
+技術書典で購入した『読み手につたわる文章 - テクニカルライティング』を読んだので学びになったトピックについて書く。
+
+## 「知らない」と書けない（P14）
+
+> こんなふうに、自転車という対象物に対する知識があれば、パーツの位置をすべて暗記していなくても自ずと正しい自転車の絵が描けるようになります。 **必要なものは絵心やセンスではなく知識なのです。** 逆に言えば、対象物を知らないと上手な絵は描けません。
+> 
+> そして自分が対象物を思っていたより「知らない」ということに、我々は気付いていないことが多いのです。上手な絵は、対象物のことを知らないと描けません。それと同じように、分かりやすい実用文は、文章力のあるなし以前に **対象物をよく知らないと書けない** のです。
+> 
+> （中略）
+> 
+> まずは自分が **対象物を知っているつもりでも意外と知らない** こと、そして **知らないものについて分かりやすい文章は書けない** ことを最初に知っておいてください。
+
+文字にすると当たり前のことのように感じるが、ブログを書いているとよく実感する。
+
+<!-- TODO: 日本語おかしいのであとで整理する -->
+技術的な内容であれば、当然対象を理解していないと書けないし、自分の考えでさえもいざ言語化しようと思うとなかなか筆が進まないことが多い。なのでそういうときはひたすら自分が何を言いたいのかをまず整理して理解しようとしてみている。
+
+## いつまでに何をしてほしいのか書こう(P25)
+>  ある日、会社であなたに「情報資産の棚卸しのお願い」というお知らせが届いたとしましょう。
+> お知らせには棚卸しの対象となる資産や、自分が会社から貸与されている資産の一覧を見る方法などが詳しく書いてありますが、結局いつまでに何をすればいいのかや、そもそも自分がこの棚卸しという作業をしなければいけない対象者なのか否かはまったく分かりません。色々と人に聞いたり調べたりした結果、もうすぐ年1回の棚卸しの時期がくるので事前告知として概要を先出ししていただけで、現時点はやるべきことやできることは何もない、ということが分かり、あなたには徒労感だけが残りました......。
+> 
+> （中略）
+> 
+> 何の食べ物だか言わずにいきなり「食べて! ほら食べて!」とスプーンを差し出されると、「え、怖い。なになになに?」となって、とても素直に口を開く気にはなれませんし、食べたところで猜疑心で味もよく分かりません。そんなときは「初めて作ったプリンが思いのほか美味しくできたので一口食べて感想を教えてほしい」というように、どういう意図で読み手に何をして欲しいと思っているのかを先に説明してあげる必要があります。
+
+わかりすぎて無限に頷いてしまった。認知負荷が高い文章を読むのはいつだって辛い。
+
+報告なのでただ把握だけしておいて欲しいのか相談がしたくて意見を求めているのかなど、読み手に求めるアクションを明示すると読み手の認知負荷が低くて良さそう。
+
+結局伝えたいことが伝わらないことには意味がないのでドキュメントを書くことの目的を見失わないようにしていきたい。
+
+## 文書構造や文章量が適切だと分かりやすい(P26)
+### 2.2.1 大枠から始めてだんだん細かくしていこう（P26）
+
+> 文章で何かを説明するときには、先に大枠を理解してもらい、それから段々細かい 内容にしていくという順番を意識しましょう。
+
+以前上司に教えてもらって以来意識するようになった。
+
+全体→詳細の順で説明することで読み手 / 聞き手が迷子になりずらくなるメリットがあると感じている。
+
+### 既知から未知に繋ごう（P28）
+> 文章を書くとき、「大枠から詳細へ」の他に意識すべきもう1つの順番は「既知から未知へ」です。
+> 技術ドキュメントを読んでいても、最初から知らない単語や知らない概念ばかりが次から次へと出てくると、「知らないことについて説明してくれているけど、その説明がまず分からない」という状態になります。まずは読み手がすでに知っていることから始めて、段々と知らないことに繋げていきましょう。
+> 
+> （中略）
+> 
+> 未知の事柄の上にさらに新しい情報を重ねようとすると、ぐらぐらと不安定な積み木の上にさらに新しい積み木を載せようとしているような状態なので、知識が脳内で安定せずにどんがらがっしゃーんとすべて崩壊してしまいます。
+> まずは知っていることからはじめて段々と知らないことへ、認知の負荷は順を追って少しずつ高くしていきましょう。
+
+あまり意識したことがなかった。
+
+一度にまとまった情報量を記述したい時にはこのあたりまで意識して書くと認知負荷が減ってよさそう。
+
+## 再利用しやすい文章にする
+### 2.4.2 並列はナカグロ（・）で書かない（P34）
+> 文章の中で並列を表そうとして「ホーム・検索・マイページ・ヘルプのタブは非表示にできません」のようにナカグロ(・)を使っていると、再利用されて箇条書きになったときに、次のような見た目になることがあります。
+> 
+> ```
+> 着せかえの設定時、以下の機能は非表示にしたり、見た目を変更したりできません。
+> ・ホーム・検索・マイページ・ヘルプのタブ
+> ・トレンドワード機能
+> ・ID連携機能
+> ```
+
+対策として、最初から箇条書きにしておくか、読点を使うといいとのこと。
+
+いつもどう書くか迷っていたが`・`で並列関係を表現すると上記のデメリットがあるので読点を使うようにしてみようと思う。
+
+### 2.4.4 リンクテキストを「こちら」にしない（P35）
+リンク切れになったときやテキストだけコピーされたときにリンク先がどこを指しているのかわからなくなるため、以下のようにどういったページなのかも含めて書くのがいいとのこと。
+
+> また「詳しくは[Shops APIのAPIリファレンス](/BankCodeAPI/reference/)を ご覧ください」
+
+また、読み手としてもリンクを踏む前にどんなページに飛ばされるのかわかるというメリットも紹介されていた。
+
+## まとめ
+具体的な知見が理由とセットで書いてあってとても勉強になった。[^1]チームで仕事をする上で認知負荷を下げる工夫の重要性を日々感じるのでこれから意識的に実践していきたい。
+
+気になったからはこちらからどうぞ。
+
+[読み手につたわる文章 - テクニカルライティング - 技術書典マーケット](https://techbookfest.org/product/3t8AGqtB65jsPtPhx6m5fr)
+
+[^1]: 余談だがちゃんと理由まで書かれているとスムーズに理解できるのでちゃんと背景や理由を説明するのは重要だと感じた。