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

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,68 @@
+---
+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)
+<!-- TODO: かく -->
+
+## 文書構造や文章量が適切だと分かりやすい(P26)
+### 2.2.1 大枠から始めてだんだん細かくしていこう（P26）
+
+> 文章で何かを説明するときには、先に大枠を理解してもらい、それから段々細かい 内容にしていくという順番を意識しましょう。
+
+以前上司に教えてもらって以来意識するようになった。
+
+全体 -> 詳細の順で説明することで読み手 / 聞き手が迷子になりずらくなるメリットがあると感じている。
+
+### 既知から未知に繋ごう（P28）
+> 文章を書くとき、「大枠から詳細へ」の他に意識すべきもう1つの順番は「既知から未知へ」です。
+> 技術ドキュメントを読んでいても、最初から知らない単語や知らない概念ばかりが次から次へと出てくると、「知らないことについて説明してくれているけど、その説明がまず分からない」という状態になります。まずは読み手がすでに知っていることから始めて、段々と知らないことに繋げていきましょう。
+> 
+> (中略)
+> 
+> 未知の事柄の上にさらに新しい情報を重ねようとすると、ぐらぐらと不安定な積み木の上にさらに新しい積み木を載せようとしているような状態なので、知識が脳内で安定せずにどんがらがっしゃーんとすべて崩壊してしまいます。
+> まずは知っていることからはじめて段々と知らないことへ、認知の負荷は順を追って少しずつ高くしていきましょう。
+
+あまり意識したことがなかった。
+
+一度にまとまった情報量を記述したい時にはこのあたりまで意識して書くと認知負荷が減ってよさそう。
+
+## 再利用しやすい文章にする
+<!-- TODO: かく -->
+並列はナカグロ（・）で書かない（P34）
+リンクテキストを「こちら」にしない（P35）
+
+## まとめ
+具体的な知見が理由とセットで書いてあってとても勉強になった。このブログでも実践していきたい。
+
+チームで仕事をする上で認知負荷を下げる工夫の重要性を日々感じるのでこれからも意識的に情報収集していきたい。