diff --git a/.textlintrc.json b/.textlintrc.json index ac6fbb0..f3d6d68 100644 --- a/.textlintrc.json +++ b/.textlintrc.json @@ -1,6 +1,8 @@ { "plugins": {}, - "filters": {}, + "filters": { + "comments": true + }, "rules": { "preset-ja-spacing": true, "preset-ja-technical-writing": true diff --git a/Makefile b/Makefile index 062f046..84000ca 100644 --- a/Makefile +++ b/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 diff --git a/content/posts/ichiban-yasashii-agile-no-kyouhon/index.md b/content/posts/ichiban-yasashii-agile-no-kyouhon/index.md index 3df8468..e17b9c1 100644 --- a/content/posts/ichiban-yasashii-agile-no-kyouhon/index.md +++ b/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: "" diff --git a/content/posts/technical-writing-book/index.md b/content/posts/technical-writing-book/index.md new file mode 100644 index 0000000..c6b243c --- /dev/null +++ b/content/posts/technical-writing-book/index.md @@ -0,0 +1,95 @@ +--- +title: "『読み手につたわる文章 - テクニカルライティング』を読んだ" +tags: ["読書ログ"] +keywords: ["読書ログ"] + +cover: "https://blog.kyu08.com/cover.png" +description: "" +date: 2024-06-06T00:21:05+09:00 +author: "kyu08" +authorTwitter: "kyu08_" +draft: false +showFullContent: false +readingTime: true +hideComments: false +color: "" +--- + +技術書典で購入した『読み手につたわる文章 - テクニカルライティング』を読んだので学びになったトピックについて書く。 + +## 「知らない」と書けない（P14） + +> こんなふうに、自転車という対象物に対する知識があれば、パーツの位置をすべて暗記していなくても自ずと正しい自転車の絵が描けるようになります。 **必要なものは絵心やセンスではなく知識なのです。** 逆に言えば、対象物を知らないと上手な絵は描けません。 +> +> そして自分が対象物を思っていたより「知らない」ということに、我々は気付いていないことが多いのです。上手な絵は、対象物のことを知らないと描けません。それと同じように、分かりやすい実用文は、文章力のあるなし以前に **対象物をよく知らないと書けない** のです。 + +文字にすると当たり前のことのように感じるが、ブログを書いているとよく実感する。 + + + +技術的な内容であれば、当然対象を理解していないと書けないし、自分の考えでさえもいざ言語化しようと思うとなかなか筆が進まないことが多い。 + + + +そうした場合にはまず自分が何を言いたいのかを整理して理解するようにしている。 + +## いつまでに何をしてほしいのか書こう（P25） + +> 何の食べ物だか言わずにいきなり「食べて! ほら食べて!」とスプーンを差し出されると、「え、怖い。なになになに?」となって、とても素直に口を開く気にはなれませんし、食べたところで猜疑心で味もよく分かりません。そんなときは「初めて作ったプリンが思いのほか美味しくできたので一口食べて感想を教えてほしい」というように、どういう意図で読み手に何をして欲しいと思っているのかを先に説明してあげる必要があります。 + + +引用部分の前に書かれていた例示のエピソードがわかりすぎて無限に頷いてしまった。認知負荷が高い文章を読むのはいつだって辛い。 + +報告なのでただ把握だけしておいて欲しいのか相談がしたいので意見を求めているのかなど、読み手に求めるアクションを明示すると読み手の認知負荷が低くて良さそう。 + +結局伝えたいことが伝わらないことには意味がないので書いて満足、ではなくドキュメントを書くことの目的を見失わないようにしていきたい。 + +## 文書構造や文章量が適切だと分かりやすい +### 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]: 余談だがちゃんと理由まで書かれているとスムーズに理解できるのでちゃんと背景や理由を説明するのは重要だと感じた。 diff --git a/package-lock.json b/package-lock.json index 285e56e..43370f5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,9 +10,9 @@ "license": "MIT", "devDependencies": { "textlint": "^14.0.4", + "textlint-filter-rule-comments": "^1.2.2", "textlint-rule-preset-ja-spacing": "^2.4.3", - "textlint-rule-preset-ja-technical-writing": "^10.0.1", - "textlint-rule-spellcheck-tech-word": "^5.0.0" + "textlint-rule-preset-ja-technical-writing": "^10.0.1" } }, "node_modules/@azu/format-text": { @@ -3020,31 +3020,6 @@ "integrity": "sha512-xxRs31BqRYHwiMzudOrpSiHtZ8i/GeionCBDSilhYRj+9gIcI8wCZTlXZKu9vZIVqViP3dcp9qE5G6AlIaD+TQ==", "dev": true }, - "node_modules/spellcheck-technical-word": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/spellcheck-technical-word/-/spellcheck-technical-word-2.0.0.tgz", - "integrity": "sha512-8hcSijidDE5oemF66L3ASQBFtFjVaiEw+YfrIksmIW6pppko83uV8eb7Pszyf0YOAT1Ew/7+O7CENWxRUXlGyQ==", - "dev": true, - "dependencies": { - "structured-source": "^3.0.2", - "technical-word-rules": "^1.4.2" - } - }, - "node_modules/spellcheck-technical-word/node_modules/boundary": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/boundary/-/boundary-1.0.1.tgz", - "integrity": "sha512-AaLhxHwYVh55iOTJncV3DE5o7RakEUSSj64XXEWRTiIhlp7aDI8qR0vY/k8Uw0Z234VjZi/iG/WxfrvqYPUCww==", - "dev": true - }, - "node_modules/spellcheck-technical-word/node_modules/structured-source": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/structured-source/-/structured-source-3.0.2.tgz", - "integrity": "sha512-Ap7JHfKgmH40SUjumqyKTHYHNZ8GvGQskP34ks0ElHCDEig+bYGpmXVksxPSrgcY9rkJqhVMzfeg5GIpZelfpQ==", - "dev": true, - "dependencies": { - "boundary": "^1.0.1" - } - }, "node_modules/sprintf-js": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", @@ -3187,12 +3162,6 @@ "node": ">=10.0.0" } }, - "node_modules/technical-word-rules": { - "version": "1.9.5", - "resolved": "https://registry.npmjs.org/technical-word-rules/-/technical-word-rules-1.9.5.tgz", - "integrity": "sha512-2sqzeb3aE23GtIO9fL9sDbqdt4vnoks7nWZRUgqEvYkjEmmQjrnVfl3WTURBZFrpgAXBNk0AMhWCj+17mzYXhw==", - "dev": true - }, "node_modules/text-table": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz", @@ -3239,6 +3208,15 @@ "node": ">=18.14.0" } }, + "node_modules/textlint-filter-rule-comments": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/textlint-filter-rule-comments/-/textlint-filter-rule-comments-1.2.2.tgz", + "integrity": "sha512-AtyxreCPb3Hq/bd6Qd6szY1OGgnW34LOjQXAHzE8NoXbTUudQqALPdRe+hvRsf81rnmGLxBiCUXZbnbpIseFyw==", + "dev": true, + "peerDependencies": { + "textlint": ">=6.8.0" + } + }, "node_modules/textlint-rule-helper": { "version": "2.3.1", "resolved": "https://registry.npmjs.org/textlint-rule-helper/-/textlint-rule-helper-2.3.1.tgz", @@ -3868,52 +3846,6 @@ "textlint-util-to-string": "^3.3.4" } }, - "node_modules/textlint-rule-spellcheck-tech-word": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/textlint-rule-spellcheck-tech-word/-/textlint-rule-spellcheck-tech-word-5.0.0.tgz", - "integrity": "sha512-BvQiWP5PZzRQQZLpGaai9XzQuQKGmJoP1wIgU8AiIGViEvX+NPoUUK4HLsZd31m0tBpQOU/4+rpy130jUf3Z8A==", - "dev": true, - "dependencies": { - "spellcheck-technical-word": "^2.0.0", - "textlint-rule-helper": "^1.1.2" - }, - "peerDependencies": { - "textlint": ">= 5.6.0" - } - }, - "node_modules/textlint-rule-spellcheck-tech-word/node_modules/textlint-rule-helper": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/textlint-rule-helper/-/textlint-rule-helper-1.2.0.tgz", - "integrity": "sha512-yJmVbmyuUPOndKsxOijpx/G7mwybXXf4M10U2up0BeIZSN+6drUl+aSKAoC+RUHY7bG4ogLwRcmWoNG1lSrRIQ==", - "dev": true, - "dependencies": { - "unist-util-visit": "^1.1.0" - } - }, - "node_modules/textlint-rule-spellcheck-tech-word/node_modules/unist-util-is": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-3.0.0.tgz", - "integrity": "sha512-sVZZX3+kspVNmLWBPAB6r+7D9ZgAFPNWm66f7YNb420RlQSbn+n8rG8dGZSkrER7ZIXGQYNm5pqC3v3HopH24A==", - "dev": true - }, - "node_modules/textlint-rule-spellcheck-tech-word/node_modules/unist-util-visit": { - "version": "1.4.1", - "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-1.4.1.tgz", - "integrity": "sha512-AvGNk7Bb//EmJZyhtRUnNMEpId/AZ5Ph/KUpTI09WHQuDZHKovQ1oEv3mfmKpWKtoMzyMC4GLBm1Zy5k12fjIw==", - "dev": true, - "dependencies": { - "unist-util-visit-parents": "^2.0.0" - } - }, - "node_modules/textlint-rule-spellcheck-tech-word/node_modules/unist-util-visit-parents": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-2.1.2.tgz", - "integrity": "sha512-DyN5vD4NE3aSeB+PXYNKxzGsfocxp6asDc2XXE3b0ekO2BaRUpBicbbUygfSvYfUz1IkmjFR1YF7dPklraMZ2g==", - "dev": true, - "dependencies": { - "unist-util-is": "^3.0.0" - } - }, "node_modules/textlint-tester": { "version": "13.4.1", "resolved": "https://registry.npmjs.org/textlint-tester/-/textlint-tester-13.4.1.tgz", diff --git a/package.json b/package.json index 31e3fa8..fa76773 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ "license": "MIT", "devDependencies": { "textlint": "^14.0.4", + "textlint-filter-rule-comments": "^1.2.2", "textlint-rule-preset-ja-spacing": "^2.4.3", "textlint-rule-preset-ja-technical-writing": "^10.0.1" }