自社 200 記事を元に整理した読みやすいテックブログを書くための Tips 集

自社のテックブログを全記事（当時約200）を読んで、読みやすいテックブログを書くためのTips集を整理しました。

Transcript

1. マスター テキストの書式設定 マスター タイトルの書式設定 自社 200 記事を元に整理した 読みやすいテックブログを書くための Tips 集
2. 流れ • 自己紹介 • 背景 • 読みやすいテックブログを書くための Tips 集 • 執筆時に意識している点 • まとめ 2
3. 3 自己紹介
4. 廣瀬 真輝（ひろせ まさき） 4 • KINTO テクノロジーズ株式会社（KTC） • DBRE グループ 兼 技術広報グループ • 技術記事の発信力向上のための取り組み • 記事のレビュー • レビュー観点の整理・標準化 • 自動レビューの仕組み導入（生成 AI / 静的解析） • 勉強会の開催 https://x.com/_p2sk_
5. 経歴 5 • 2013 年 – 2022 年 10 月 • ファッション EC サイト運営会社 • 前半：サーバーサイドエンジニア • 後半：データベースエンジニア • 2022 年 11 月 • KTC 入社 • 2024 年 5 月 • 技術広報 G 兼務
6. アウトプット歴 6 • Qiita • 累計 93 記事、2255 Contributions、150 万 PV（30 万 PV /年） • 会社のテックブログ • 約 20 記事 • LinkedIn Learning • DB パフォーマンスチューニングコースの動画講師 (約 2 時間) • 国内カンファレンス登壇 • 3 回（db tech showcase） • 技術コミュニティ勉強会での発表 • 30 回
7. 背景 7
8. KTC のテックブログ • 2022 年 7 月：最初の記事公開 • 2 年間で日本語記事 242本！/英語記事162本！ • ノルマがない状況で、自主的にこの執筆数はすごすぎる • PV 数も着実に増加 8
9. 全記事読みました • 面白い記事が沢山！ • もっと沢山の人に読まれるべき価値のある記事が多い • 少しの工夫でもっと価値を高められる記事も沢山 • タイトルをもっと良くできそう等 9
10. 全記事読みました • 面白い記事が沢山！ • もっと沢山の人に読まれるべき価値のある記事が多い • 少しの工夫でもっと価値を高められる記事も沢山 • タイトルをもっと良くできそう等 10 これまでの記事を振り返り 記事の読みやすさに特化した Tips 集を整理したので シェアしたい
11. 11 読みやすいテックブログを 書くための Tips 集
12. 12 読みやすいテックブログを 書くための Tips 集 ①タイトルにこだわる
13. タイトルにこだわる 13 • 内容を読むか判断する、非常に重要なもの • 時間をかけて考える価値あり • X でのリポストされやすさにも影響
14. タイトルにこだわる 14 • 記事のジャンルがわかること • iOS / Golang / MySQL など、どのジャンルのエンジニアも 知っているであろうワードを入れることで、記事の領域を明示
15. タイトルにこだわる 15 • 短く簡潔よりも、長く具体的 iOS 領域の話だと一目でわかる 同じ領域の人に届くより具体的なワード 動詞が入っており、主題が想像しやすい
16. タイトルにこだわる 16 • 短く簡潔よりも、長く具体的 iOS 領域の話だと一目でわかる 同じ領域の人に届くより具体的なワード 動詞が入っており、主題が想像しやすい ※廣瀬が適当に作成 なんのテストなのかわからない（タグに頼るのは NG） どんな画像なのかわからない 画像管理に関するどんな課題解決なのかわからない
17. タイトルにこだわる 17 • 数字を入れることで具体性・説得力が増す
18. タイトルにこだわる 18 • 良いタイトルとは：まとめると • 記事のジャンルがどんなエンジニアにも分かるワードを入れる • 同じ領域の人にしかわからなくても OK な具体的なワードも一緒に • 動詞を入れると「何をしたのか」伝わりやすい • 数字を入れることで具体性・説得力が増す • 短くて簡潔なタイトルより、長くて具体的なタイトルを • タイトル作成後に「自分が読みたくなるか？」と 問いかけてみる
19. 19 読みやすいテックブログを 書くための Tips 集 ②背景を説明する
20. 背景を説明する 20 • 「なぜこの記事を書いたのか」を明示する
21. 背景を説明する 21 • もし背景がないと・・ • どういう視点で読むべきか判断が難しい • 「他の記事の方が分かりやすいのでは？」と思われる懸念も
22. 背景を説明する 22 • 背景の明示により、納得感を持って読み進められる
23. 背景を説明する 23 • 手厚すぎても損はない • 全体の 1/3 くらいが背景 • 記事内のキーワード（GDPR / Cookie）の解説 • KTC における現状と課題 • の 2 点が手厚く説明されており専門外の人も読みやすい
24. 背景を説明する 24 • 手厚すぎても損はない • 全体の約半分が背景 • Kotlin で OGP を取得する時に文字コードで苦労 するよ、ということが再現方法を含めて丁寧に 説明されていることで、後半の解決方法の提示 の価値が高まる
25. 背景を説明する 25 • 手厚さ MUST ではない • もちろん簡潔にでも、具体的であれば OK • 背景（執筆理由）を書くこと自体は MUST といっても過言ではない
26. 背景を説明する 26 • まとめ • 「なぜこの記事を書いたのか」を明示 • 解説記事なら「探しても分かりやすいドキュメントがなかった」等 • 課題解決事例なら「xx領域においてはxxという課題があります」等 • 参加レポート系なら「感動した・勉強になったのでシェアしたい」等 • 必要に応じて記事内のキーワードを解説 • 「GDPR とは」 • 特有な状況であれば分量が多くなったとしても手厚く説明
27. 27 読みやすいテックブログを 書くための Tips 集 ③ターゲットを明記する
28. ターゲットを明記する 28 • Must ではないが、あると親切 • 自分が想定読者か判断しやすい
29. ターゲットを明記する 29 • 見出しとして独立させるのも Good
30. ターゲットを明記する 30 • 同じ境遇の人は（ほぼ）必ずいる • 初心者からエキスパートまで、その時々で欲しい情報は違う • step by step な how to 記事 • 高難度の意思決定を必要とするリアーキテクチャ事例 • 詳細に背景を書くことで、刺さるべき人に刺さる記事になる • 「詳細な背景の提供」≒「ターゲットの明記」
31. ターゲットを明記する 31 • 刺さるとは • 以下のような読後感を引き出すこと • ためになった / 参考になった / 勉強になった • 自分も同じ経験をした / 同じことを思った（同意） • 自分はこう思う（議論したくなる） • すごい / 面白い / 楽しそう • あとで読めるように保存したい • 上記の読後感を引き出すためにも背景やターゲットの明記は有効
32. 32 読みやすいテックブログを 書くための Tips 集 ④認知負荷を最小化する
33. 33 • 図を分かりやすく • キャプションをつける 認知負荷を最小化する
34. 34 • 図を分かりやすく • キャプションをつける 「ここで説明しているから伝わるだろう」とならずに 丁寧にキャプションをつけているのが Good！ 認知負荷を最小化する
35. 35 • 図を分かりやすく • 特に着目して欲しいポイントをマーキング • （option）画像が何を表しているのか文字で補足 認知負荷を最小化する
36. 36 • 文字の塊を分割し、視覚的な圧迫感を軽減する 認知負荷を最小化する
37. 37 • 文字の塊を分割し、視覚的な圧迫感を軽減する ※廣瀬がわざと塊にしたバージョン 認知負荷を最小化する
38. 38 • 動画でイメージを促す 認知負荷を最小化する
39. 認知負荷を最小化する 39 • 見出しの前後に「つなぎの一言」を入れる • 次の見出しへと読み進めるのは意外と認知負荷が高い
40. 認知負荷を最小化する 40 • 見出しの前後に「つなぎの一言」を入れる • 次の見出しへと読み進めるのは意外と認知負荷が高い ここまで「調査してた」ことがわかる 次の章が「検討した対応策」だとわかる 「調査」を踏まえた「対応策」と前後の章を接続
41. 認知負荷を最小化する 41 • 読みやすさを向上させる工夫 • 読点「、」の打ち方が適切、多すぎない • 同じことを伝えたい場合、可能な限り簡潔で短い表現 • まとめると • 読み手の理解に必要なエネルギー（認知負荷）を最小化する • そのために • 自分で声に出して読むと、読みづらい箇所がわかる • 一回書いて終わりではなく、通しで読んでブラッシュアップ！ • ブラッシュアップに生成 AI を活用するのも有効
42. 42 読みやすいテックブログを 書くための Tips 集 ⑤結果を工夫する
43. 結果を工夫する 43 • ポジティブな結果を数字で提示すると説得力が増す • 30% 高速化できた • コストが 5 分の 1 になった • アンケート結果で満足度が 4.5 だった • 「課題が解決できた」という一言だけでも OK • 数字ではなく「できた」「できなかった」の 2 値のケースもある • 視覚的な改善結果は画像・動画を用いる
44. ポジティブな結果を数字で提示する 44
45. ポジティブな結果を数字で提示する 45
46. ポジティブな結果を数字で提示する 46 前後比較も Good!
47. 視覚的な改善結果は画像・動画を用いる 47
48. 48 読みやすいテックブログを 書くための Tips 集 ⑥その他
49. 社内固有の用語は解説した上で使う • プロジェクト名など、社内独自用語は簡単に説明を 加えてあげると親切 49
50. 上から目線と捉えられかねない表現は避ける • 「初心者向けの記事なので、これくらいは理解できると思います」 • 「初心者の方にとって、少しでもこの記事がお役に立てたら幸いです」 • 「わからない人はこの記事で勉強してください」 • 「この記事がどなたかの参考になりましたら幸いです」 ※ChatGPT に作ってもらった例 50
51. 事実をありのまま伝える必要がないケースを考慮 • 読者にとって不要な情報はカット or 短くまとめる • xxなことがあり、xxからxxという指摘を受けたので、xxしました • xxという理由からxxしました 51
52. ネガティブな感情を入れない • 技術記事であれば感情を記事に入れない • 事実と思考の羅列 • 技術的な失敗などを感情を入れずに書くのは問題ない • 失敗から得た学びは、読者と自分に利益があるため • 入れるなら、ポジティブな感情だけに 52
53. 53 読みやすいテックブログを 書くための Tips 集 まとめ
54. まとめ ① タイトルにこだわる ② 背景を説明する ③ ターゲットを明記する ④ 認知負荷を最小化する ⑤ 結果を工夫する ⑥ その他 54 社内ではチェックリスト形式て提供中
55. 55 執筆時に意識している点
56. 記事の「強度」を上げる • あらゆる創作物には「強度」の概念がある • 記事の強度を強めることはポジティブにバズるために有利 • 強度のある記事は企業ブランディングとしても有効 56
57. 最高強度の技術記事＝論文 • 論文の構成を引用することで強度を担保する • 背景 • 概要 / contribution • 「この記事の contribution」は何なのか？を一言で言える状態が望ましい • 関連研究 • 自社、自チームの記事であっても引用することで強度は上がる • 将来的には会社間でテックブログを引用し合う、みたいな世界観も • 提案手法 • 結果 • 従来手法（Before）と比較する • future work • (appendix) 57
58. 論文に必要な要素＝「新規性」 • テックブログにおける「新規性」≒「相対的 Update」 • 課題が新しいこと • KTC（自動車業界）独自の課題なだけでも興味を惹く • 解決方法が一般的な場合でも価値の高い記事に • アプローチ / 結果が新しいこと • 現状のアーキテクチャを踏まえてxxな改善を実施 • 現状よりも N% 高速化できた • 現状よりも UX を改善できた • 解説記事なら • 他の既存記事よりも分かりやすい • 検索しても LLM を使っても一筋縄ではいかない手順を解説 58
59. 取り組んだ業務の強度以上の強さは出ない • 記事の強度を上げようとする → 業務の強度改善につながる • 比較していなかった → 比較しよう • 感覚で決めていた → 根拠を示そう / 残そう • 全力で記事を書くことのメリット • 自分に対して：足りないところ・強み（できていること）が見えてくる • 読み手に対して：ターゲットに刺さりやすい / 参考になりやすい 59
60. 「途中の失敗や検証過程」にも大きな価値 • 失敗、エラー、障害の紹介は読者にとって「助かる」 • 同じ轍を踏まなくて済む / 踏んだ後の解決策がわかる • 期待した結果と得られた結果が違っても 1 つの価値ある学び • 「結果だけ提示」は他者も適用可能なのか判断しづらい • 「なぜこのアーキテクチャにしたのか」 • 「なぜこの実装にしたのか」 • といった判断基準は読者にとって応用が効く情報 60
61. 日々の業務を記事のネタにする • ゼロから文字を書くのはしんどい • 日頃から作業内容、疑問、工夫、学びなどをメモする習慣づけ • メモを 1 記事に「要約」するのはゼロから書くよりかなり楽 • 「要約」なので生成 AI で初稿が完成する未来も • 例：廣瀬のテックブログ • 元ネタは全部コンフルの作業ログや議事録 • 40 記事程度を 1 つのテックブログへと凝縮 → 「濃く」なる・強度が増す 61
62. 実践している内容 • 普段からドキュメントをかく • 思考や発見、失敗もメモ • 普段から比較検討を実施 • 業務中に「テックブログに書くなら、こういう比較も必要だよな」を考えるように • ドキュメントを「まとめる」形で初稿を作る • 初稿完成までと同程度の時間をかけてブラッシュアップ 62
63. 63 まとめ
64. 読みやすさに特化した Tips 集を整理 ① タイトルにこだわる ② 背景を説明する ③ ターゲットを明記する ④ 認知負荷を最小化する ⑤ 結果を工夫する ⑥ その他 64 社内ではチェックリスト形式て提供中
65. 執筆時に気をつけている点をシェア • 論文の構成を使って記事の強度を担保 • 記事の強度を上げようとすると業務の強度も上がる • 記事の Contribution を一言で言える状態にする • 失敗や苦労、判断基準など「過程」も記載する • 日頃から溜めたドキュメントを要約する形で初稿を作る • 初稿完成後に同程度のエネルギーでブラッシュアップする 65
66. 「発信力」はポータブルスキル 66 • 対外的な発信実績は WEB 上に残り続ける • 自分の「発信力」の証明に • 身につけた「発信力」の寿命は非常に長い • 対象の技術が変わっても、同じ強度の記事を書ける再現性の高い能力 • 自分のキャリアにとっても武器になる • もちろん（ブランディングとして）会社にとっても武器・貢献になる
67. Thank You!! 67