技術書から学ぶ、 読みやすい文章の極意 / The Art of Clear Writing: Lessons from Technical Books

Transcript

1. 技術書から学ぶ、 読みやすい文章の極意 22nd Apr, Jagu’e’r Tech Writers #13『テクニカルライティングの上達』 Speaker: Kento Kimura
2. わたしは… • 所属： Technical Solutions / Sales Engineer • 担当： パブリッククラウドのアーキテクト知識を活かした 　 Datadog のプリセールス技術支援 • 表彰： Google Cloud Partner Top Engineer 2023-25 Jagu'e'r Award 2023, 2024 優秀賞 2022-24 Japan AWS All Certifications Engineer AWS Community Builder(Cloud Operations, since 2024) • 好きな Google Cloud サービス： Cloud Run, Cloud Observability 木村 健人 (Kento Kimura) Datadog Japan GK History データセンター管理運用→パブリッククラウド技術支援 →プリセールス技術支援 Partner Top Engineer 2023 Partner Top Engineer 2024 Partner Top Engineer 2025
3. 3 おはなし 1 実践可能な執筆ルール 2 読みやすい文章 3 理解しやすいコード 4 見やすいスクリーンショット 5 今日からできること
4. 4 イントロ
5. 5 技術書の著者は執筆量が段違い 技術ブログの平均文字数は1本あたり??????????字程度 技術書の平均文字数は1冊あたり??????????字程度
6. 6 技術書の著者は執筆量が段違い 技術ブログの平均文字数は1本あたり4,500~5,000字程度 技術書の平均文字数は1冊あたり80,000~120,000字程度 + 幅広い対象と知識・章立て・内容の正確性 etc...
7. 7 この技術書がすごい 『GitHub CI/CD 実践ガイド』 @tmknom • GitHub Actions から CI/CD の基本を学べる • 優れた網羅性と、学習しやすい流れの章立て • 最高の読書体験を目指した著者の執筆ルール • 文章の背景となる、他の名著への言及と引用
8. 8 この技術書がすごい 『GitHub CI/CD 実践ガイド』 @tmknom • GitHub Actions から CI/CD の基本を学べる • 優れた網羅性と、学習しやすい流れの章立て • 最高の読書体験を目指した著者の執筆ルール • 文章の背景となる、他の名著への言及と引用 過去に『読みやすい技術書を書く技術』を執筆 ◦ 「出ない神本より出るクソ本」と言う名言を残す😂 ◦ 完璧を目指さず、書き終えることを最初の目標にする ◦ その上で、必要な校正ツールを活用する
9. 9 この著者がすごい 執筆のノウハウは Zenn の記事 「書籍『GitHub CI/CD実践ガイド』を読みやすくする技術」で公開されている！！ 本日はここから、読みやすい文章の極意を学びます📖
10. 10 注意：技術書と技術ブログの違い • 技術書に求められるもの →読者に手に取ってもらえるための完成度 　内容の正確性・目的・網羅性 • 技術ブログに求められるもの →話題性・即時性 　著者の学びになるか ＋読者に手に取ってもらえるための完成度 　内容の正確性・目的・網羅性 　
11. 11 注意：技術書と技術ブログの違い • 技術書に求められるもの →読者に手に取ってもらえるための完成度 　内容の正確性・目的・網羅性 出版日やかける時間を考えると、適切な売上や報酬を見込む必要がある • 技術ブログに求められるもの →話題性・即時性 　著者の学びになるか ＋読者に手に取ってもらえるための完成度 　内容の正確性・目的・網羅性 書き手のエゴがある程度許される！エゴがニーズに一致するとバズる！ 　
12. 12 読みやすい文章
13. 13 読みやすい文章の3ポイント • 読点は一文につき最大ひとつ 最初にして最大の難関ポイント！！ 読点が一つだと、文が半強制的に短くなる。加えて、表現が端的に洗練される。 • 一文の中で同じ助詞は使わない 意識することで適用できるポイント！ 日本語は多くの言い回しがある。多用される助詞が連続することを避けられる。 • 校正ツールで問題を早期検出する ある程度事前知識・準備が必要なポイント！ prh, redpen, textlint で表記揺れ・タイプミス・口語表現・技術表現を修正する。
14. 14 理解しやすいコード
15. 15 理解しやすいコードの4ポイント • コードを完全な状態で掲載する 特に、書籍では紙面の都合で省略しがちだが… 技術ブログでも全て掲載することで再現性があり・写経ができるので、読者に役立つ • 着目すべきポイントへコメントで誘導する ただのコードではなく、コメントの誘導が差別化要因 書籍では読者の誘導だが、技術ブログでは理解度を示しコードを差別化できる • 詳細説明のタイミングで該当コードを再掲する 書籍ではページの都合で再掲が望ましいが、技術ブログの場合は GitHub のリンクなどでも良いかも • ファイルレイアウトを明示する 複数ファイルの関係性やどこに配置するかを整理できる
16. 16 見やすい画像と スクリーンショット
17. 17 見やすいスクリーンショットの2ポイント • 操作手順を省略しない ただの画面のスナップショットの連続ではなく、単一画面に説明を入れる！ 画面自体は簡単に再現・確認できるが、操作手順や画面の説明は読者の行動を喚起する • スクリーンショットからノイズを除去する 取りっぱなしのスクリーンショットは価値がない 説明のために必要最低限に情報を削ぎ落とすことで、読み手に優しくなる！ 技術ブログの場合は画像のサイズや形も重要！ スマホ・タブレット・PC での表示の際にも注意！
18. 例：技術ブログ内の画像 サイズを考えずに画像を挿入した例 （スマホだと見やすいので見逃しがち） 18 位置とサイズを調整した例
19. 19 まとめ
20. 20 まとめ • 兎にも角にも「書き切ること」が重要 • 読者を想定する ◦ どうしたら「読みやすい」か ◦ どうしたら「理解しやすい」か ◦ どうしたら「見やすい」か • ツールの力を活用する ◦ LLM に書かせるのではなく、直させる ◦ 最低限の校正ツールは手間 < 有用
21. Thank you