技術記事を読んでほしい私が、「伝え方」で気をつけている5つのポイント（具体例つき）
最初にまとめ
私は Zenn で技術記事を書くとき、以下の 5 つのポイントを意識しています。
- 読みたくなるタイトルにする
- 結論を先に書く
- 流し読みできるようにする
- 前提を伝える
- ハッピーかつポップに！ 🥳
詳細は以降で説明します。
この記事の概要
技術記事を書く上では、読んでもらうための表現の工夫が必要です。
どんなテーマ・どんなことを説明するかといった記事の内容はもちろん大事ですが、その内容を効果的に伝えるために工夫できることがたくさんあります。
この記事では、読みやすさ・読まれやすさを向上させるために個人的に行っている工夫を紹介します。
記事の題材を決め、説明すべき内容を一通り書ききった後に見直しているポイントです。
想定読者
この記事は、以下のような人を想定して書いています。
- Zenn や Qiita、個人のブログに技術記事を書いたことがある
- 書いた記事をもっと多くの人に読んでほしい
- 読みやすい記事を書くために工夫したい
書かないこと
以下のような内容は書きません。
- 記事のテーマの決め方
- 記事を書き上げるまでのプロセス
- 内容の書き方・調べ方
1. 読みたくなるタイトルにする
どんなにいい記事を書いても、読んでもらえなければ意味がありません。
記事の本文を書くことに集中していると忘れがちですが、 記事を開いてもらえるかどうかは、タイトルがほぼ全て です。
それもそのはず、記事（ページ）を開く前に見るのはタイトルだけです。検索で見つけたとき、SNS でシェアされたとき、Zenn のトップページで見つけたときなど、どの場合もタイトルが最初に目に入り、それを元に開いてみるか判断します。
読んでほしい人に届くように、タイトルを工夫しましょう！
（参考）記事を見つける状況は大きく3種類
自分なりに、読者が記事を開くケースを分類しておきます。
大きく 3 種類に分類します。
-
特に目的がなく、受動的に見つける場合🚶♂️
- Zenn のトップページや記事一覧
- Twitter や Slack などでの共有
-
能動的に目的の情報を探している場合🕵️
- 検索エンジンでの検索結果
-
一度読んだ記事を探す（思い出す）場合🧠
- 過去に読んだ記事をもう一度読むため、履歴・ブックマークから探す
3 のパターンは、そもそも一度読んでもらわないことには発生しないので、1,2 がより重要といえます。
1 のケースでは、タイトルが目に入ったときに「読んでみようかな」と思わせるようなタイトルが必要です。
2 のケースでは、想定読者が検索しそうなワードを含めておけば、検索結果に引っかかりやすくなります。
3 のケースでは履歴から探すために検索しやすいタイトルにしておくことや、記事タイトルから内容を思い出しやすいようにしておくことが重要です。
それぞれのケースをイメージしながらタイトルを考えてみると、どんなキーワードを入れたらよいか考えやすいかもしれません。
大事なこと："for me" を感じさせる
読者がタイトルを見た瞬間に、「読んだら自分の役に立ちそうだ」「自分に関係ありそうだ」という "for me" を感じさせることを意識しています。
"for me"（筆者からすれば "for you"）を意識して書いたタイトルは以下の例があります。
VueやJSXは好きだけどSPAは要らない、そんなあなたに Astro
この記事は、 Astro という Web フレームワークを紹介した記事です。「Vue や JSX は好きだけど SPA は要らない」という説明でに以下の意図を込めました。
- Vue や JSX と似た書き方ができ、かつ SPA ではないという Astro の特徴
- Vue や JSX をすでに触ったことがある人、特に SPA は求めていないという思いがある人に読んでほしいという意図
言語・ライブラリ名など、主要なキーワードをタイトルに盛り込む
言語名やライブラリ名を入れておけば、普段その言語・ライブラリを使っている人の目に留まりやすくなります。
また、検索に引っかかるように（SEO を意識して）必要なキーワードを入れるようにします。
「こういうキーワードでググるかな？」と考えてみるといいでしょう。
例えば、以下のように具体的な言語名がないタイトルの場合、他の言語の話と区別しづらいです。
for文の書き方
具体的な言語名やライブラリ名を含めておくとよいでしょう。
【JavaScript】for文の書き方
キャッチーにする
タイトルに読みたくなる仕掛けを作るといいでしょう。
読者の興味を引くことを意識してつけたタイトルの例を紹介します。
【CSS】まだホバー時のスタイルを :hover だけで指定してるの？
たとえば、 ホバースタイルを指定するときに気をつけること みたいなタイトルでもいいわけですが、これだとありきたりです。
問いかけるようなタイトルにすることで、自分（読者）のこととして考えさせる仕掛けを入れています。さらに、 :hover 以外の記述のことを紹介していることを端的に伝えられます。
（やや煽り気味になってしまいましたが、）これにより多くの人に読んでもらえました。
ただし、煽りすぎたり、嘘を書いてしまうのは当然よくありません。内容を表現するための修辞の範囲で行いましょう。
「○個の理由」「○個のルール」
読みたくなるタイトルの汎用テクニックとして「○個の理由」「○個のルール」のように数をタイトルに含める方法があります。
CSSを書くときに気をつけていること
管理しやすいCSSを書くために気をつけている10のこと
私の過去の記事から具体例を紹介します。
よりよいCSSを書くための、CSS / Sass (SCSS) 30のルールとその理由
【CSS】gridでできるこんなレイアウト10選（grid関連プロパティ総ざらい）
それでも私が<wbr>でなくinline-blockで改行調整をする、たった1つの理由
- よりよいCSSを書くための、CSS / Sass (SCSS) 30のルールとその理由
- 【CSS】gridでできるこんなレイアウト10選（grid関連プロパティ総ざらい）
- それでも私が<wbr>でなくinline-blockで改行調整をする、たった1つの理由
数が少なければ、「重要なことがまとまっているのか！」という印象を与えることができます。
一方で数が多ければ、「そんなにいろんな内容が網羅されているのか！」という印象があります。
どちらにしても読みたくなるきっかけにつながるので、お得な方法です。
先に数が示されていることで、読者は先に「頭の中に枠を用意しておく」ことができるので、読んでいる途中にあとどれくらいあるかわかりやすくなり、読みやすくなります。
ときには記事を分割することも考える
記事に内容を盛り込み過ぎている場合、タイトルを付けるのが難しくなる場合があります。
その場合は、タイトルでどうにかしようとせず、記事を分割して、1記事1トピックに絞るようにしてみましょう。
読者としても読みやすくなりますし、検索での見つけやすさも上がります。
私が書いた記事を例に出すと、例えば以下の 2 つの記事は当初 1 つの記事にしようとしていました。
前者の記事を書こうと調べている最中に発見した内容を、後者の記事に独立させた形です。
前者の記事の一部としてしまうと、その内容が見つけづらくなってしまうことを懸念して、分割しました。
2. 結論を先に書く
記事を書く際は、できるだけ結論を先に持ってくるようにします。
主な理由としては、以下の 3 つです。
- 技術記事においては、結論だけ知れれば解決することが多いから（特にバグ解決系であれば）
- それ以降の解説を読みたいか（自分に関係がある記事なのか）を判断できるから
- 先に結論が頭に入っていれば、その後の解説が理解しやすくなるから
「PREP 法」として知られている通り、結論を最初に話す方法は効果的な構成です。
話したい順序で書いてしまうと、どうしても「前提」→「解説」→一番最後に「結論」としたくなりがちですが、読者としてはとりあえず結論が知りたいです。
読者として記事を読むとき、先に結論を読むために一番下までスクロールした、という経験がある人もいるのではないでしょうか。
理由にも書いた通りですが、結論を先に書く目的は 中身を読まない人のためだけではありません。本文を全文を読むとしても、結論が先に来ていることは効果的です。
先に結論が頭に入っていれば、その後の解説を読む際に、「なんのためにこの説明がされているのか」を理解しやすくなるからです。
記事の最初に結論を書く
可能な限り、ファーストビューでその記事の要約が伝わるようにしています。
例えば、以前書いた 【HTML】dl, dt, ddで組みたくなる表、tableにするのがいいかもね（スクリーンリーダーと検索エンジンのために） という記事では、 「はじめに結論から」 という見出しのセクションを最初に持ってきています。そして、「詳細は以降で説明します」として、以降の本文で理由や具体例を補足しています。
セクションの中でも最初に結論を書く
結論を先に持ってくるのは、記事全体の構成だけの話ではありません。
各セクションの中でも、そのセクションの結論を先に書くようにしています。
（理由は前述のとおりです）
例えば先ほどの文を例にしてみましょう。
先に詳細な説明をされても、何の話かわかりません。
- 技術記事においては、結論だけ知れれば解決することが多いから（特にバグ解決系であれば）
- それ以降の解説を読みたいか（自分に関係がある記事なのか）を判断できるから
- 先に結論が頭に入っていれば、その後の解説が理解しやすくなるから
そのため、記事を書く際は、できるだけ結論を先に持ってくるようにします。
結論を先に書くことで、読みやすくなります。
記事を書く際は、できるだけ結論を先に持ってくるようにします。
主な理由としては、以下の 3 つです。
- 技術記事においては、結論だけ知れれば解決することが多いから（特にバグ解決系であれば）
- それ以降の解説を読みたいか（自分に関係がある記事なのか）を判断できるから
- 先に結論が頭に入っていれば、その後の解説が理解しやすくなるから
3. 流し読みできるようにする
読みやすさを確保するために確認しているポイントが「流し読みできるかどうか」です。
もちろん頭から最後まで読んでもらえることが一番ですが、普通そんな時間や気力はありません（少なくとも私が記事を読むときは大抵の場合流し読みしてしまいます 🙈）。
例えばこの記事でも、具体例をコードブロックで囲むことで、そこだけ拾い読みできるようにしています。詳しい説明が読みたくなったら、そのときだけ周囲の文章を読んもらえばよいのです。
具体的な工夫のポイントを以降で紹介します。
太字を使う（見た目のメリハリをつける）
文章を書くことに集中していると、装飾に頭が回らなくなってしまいがちです。
しかし、太字を使うことで、見た目のメリハリをつけることができ、ざっとスクロールしたときにも重要な箇所を把握しやすくなります。
例えば、上記の文章を早速例にしてみましょう。
装飾を何もつけないと以下のようになります。
文章を書くことに集中していると、装飾に頭が回らなくなってしまいがちです。
しかし、太字を使うことで、見た目のメリハリをつけることができ、
ざっとスクロールしたときにも重要な箇所を把握しやすくなります。
しかし、重要な箇所（特に伝えたい箇所）を太字にすることで、全文を読まずとも、この段落の大意がつかめるようになります。
文章を書くことに集中していると、装飾に頭が回らないことは多いです。
しかし、太字を使うことで、**見た目のメリハリをつける**ことができ、
ざっとスクロールしたときにも**重要な箇所を把握しやすく**なります。
記事の公開前に、太字の箇所だけ拾い読みして主要な内容が伝わるかどうか確認してみるとよいでしょう。
箇条書きを使う
項目が複数並ぶとき、箇条書きを使うと通常の文章と比べて読みやすくなります。
理由は主に以下の 2 つです。
- 項目がいくつあるのか把握しやすい
- どこからどこまでが 1 つの項目なのか把握しやすい
さっそく、上記の文を例にして比較してみましょう。
項目がいくつあるのか把握しやすいことや、どこからどこまでが 1 つの項目なのか把握しやすいことなどが理由です。
理由は主に以下の 2 つです。
- 項目がいくつあるのか把握しやすい
- どこからどこまでが 1 つの項目なのか把握しやすい
絵文字を使う
技術記事では、コードサンプルを示す際などに「こう書いたほうがいい」「こう書くと良くない」といった紹介することが多いです。
こういった対比は絵文字を使うことで視覚的に理解しやすくなります。
（GOOD, BAD を表す絵文字としては 👍👎 や 🙆🙅 もあるのですが、これらはパッと見で色の違いがないので個人的には ✅❌ が好みです）
変数名は省略せずに書きましょう。
NG例
const btn = document.querySelector('button');
OK例
const button = document.querySelector('button');
変数名は省略せずに書きましょう。
❌ NG例
const btn = document.querySelector('button');
✅ OK例
const button = document.querySelector('button');
目次（階層構造）は適切か
Zenn では、見出しを元に目次が生成されます。
記事の公開前には目次を読み直して、目次だけ見て目的の箇所にたどり着けるか を確認しています。
また、目次を確認することで、文書構造が適切かどうかを把握することにつながります。
目次に違和感があれば、セクションの順番を入れ替えたり、セクションを分割したりすることを検討します。
（必要な場合）図を入れる
文章だけで説明が難しい場合、図を入れることで理解しやすくなります。
必ずしも説明のためでなくとも、イラストを入れることで見た目のメリハリをつけることも効果的です。
4. 前提を伝える
同じ内容を伝えるにしても、話の前提が伝わっているかどうかで伝わり方が変わってしまいます。
変な誤解を生まないようにするため、そして内容を理解してもらいやすくするため、筆者と読者の間に齟齬・すれ違いが起きないように気をつけます。
自分では気づきにくいので、他の人に読んでもらったり、 ChatGPT に指摘してもらうのもよいです。
記事の主題が伝わるようにする
当たり前ではありますが、その記事に何が書いているのかをわかってもらう必要があります。そうでないと、読んだ後に「思ってたんと違う」となってしまいます。
これに関しては可能な限りタイトルで伝わるべきです。
また、逆に「この記事で話さないこと」を書いておくのも効果的です。
対象読者が伝わるようにする
記事を書く際には、どんな人に読んでもらいたいかを意識して書くことが重要です。
たとえばこの記事であれば、「技術記事の書き方」をテーマにしています。アクセスしてくる人の属性としてはざっくりと以下のようなカテゴリが考えられます。
- すでにバリバリ技術記事を書いている人
- 技術記事を書いたことがあって、より工夫したいと思っている人
- 技術記事は書いてみたいけど、1 回も書いたことはない人
- そもそも技術記事を書きたいと思ってない人
しかし、この記事はこれらすべての属性の人に読んでもらおうとは思っておらず、「技術記事を書いたことがあって、より工夫したいと思っている人」を想定して書いています。これがあらかじめ伝わっていないと、対象としていない人にとっては読んでも役に立たない情報になってしまいます。
そのため、この記事でも冒頭で対象読者を明示しています。
対象読者を「書く」ではなく、「伝わるように」としたのは、わざわざ書かなくても判断できる場合はわざわざ書かなくてもよいからです。
例えば「CSS で要素を真ん中寄せにする方法」といったタイトルの記事であれば、今 CSS を書いていて、真ん中寄せにしたくて困っている人に向けて書いていることは明白です。そこでわざわざ CSS を知らない人のこと考慮した断りをいれる必要はありません。
さらにいうと、タイトルから対象読者が読み取れるようになっていると、より親切です。
前提知識が伝わるようにする
対象読者の話とほぼ同じですが、同様にその記事を読むうえで前提となる知識が伝わっているかも重要です。
技術系の記事であれば、その言語やライブラリのことを
- そもそも知らない人
- 勉強中の人
- 普段から業務や趣味で使っている人
- 設計思想やベストプラクティスにまで詳しい人
など、どの程度の知識を前提として記事を書いているのか意識しておくとよいです。
想定している状況や用途が伝わるようにする
書いている自分にとっては当たり前と思っていても、読者にとってはそうではない想定をしている場合もあります。
- プロダクトに使える手法なのか、趣味レベルでしか使えない手法なのか
- Web 開発の話なのか、アプリ開発の話なのか
- 事業会社の話なのか、受託開発の話なのか、フリーランスの話なのか
などなど、人によっては「当たり前」の前提が異なることがあります。
動作確認したバージョン・日付を書く
Web に公開するからには、何年・何十年後かに読まれる可能性もあります。
執筆時点の当たり前も、未来には異なっているかもしれません。
つまり、「今の筆者」と「n 年後の読者」の間で齟齬が起こってしまう可能性があります。
読者側が記事の公開日を確認することももちろん大事ではありますが、筆者側も動作確認したバージョンや日付を明示的に示しておくことで、内容の正しさ・信頼性を判断・検証しやすくなります。
5. ハッピーかつポップに！ 🥳
この項目は自分の信条の部分が強いです。
知識を共有することによって誰かの役に立つこと、開発体験やコードがよりよくなることを目的として記事を書いています。読む人にはハッピーになってもらいたいのです。記事自体がエンタメになればより嬉しいです。
真面目に説明しているだけだと難しい印象を与えてしまいますし、読みにくくなってしまいます。できるだけポップな表現になるように心がけています。
誰かを攻撃するような表現になっていないか
誰かを批判したり、不快な気持ちにさせることは目的ではありません。
表現が攻撃的になっていないか確認します。もしも誤解を生みそうな場合は、断りをいれるようにします。
サンプルコードに身近な題材を使う
実務に近いサンプルはもちろん役立ちますすが、そればかりだとつまらなくて読みたくなくなってしまいます。
ちょっと楽しくなるようなサンプルコードを使うようにしています。
単におもしろさの意味だけでなく、わかりやすさの点でも効果的です。読者がすでに知ってる概念を適用することで、新しい概念を理解しやすくなります。
例えば、私の書いた「【初学者向け】具体例で学ぶ TypeScript 練習問題集」という記事の一部では、実務では絶対使わなそうなポケモンのコードをサンプルとして載せていたりします。
const pikachu: Pokemon = {
name: "ピカチュウ",
type: ["でんき"],
};
const charizard: Pokemon = {
name: "リザードン",
type: ["ほのお", "ひこう"],
};
テンションを上げる！
文章全体のテンションを上げるために、以下のような工夫をしています。
- 文末を「！」にする
- 絵文字を使う 😌
とはいえ、やりすぎると頭悪そうな印象を与えてしまうので、塩梅は調整しましょう。
渡しの場合は、書き進める最中は普通に書いて、最後に読み返したときに重い印象だったら調整するくらいで使っています。
文章全体をポップにする手法としては、やめ太郎さんの記事のような会話形式も 1 つですね（私には使いこなせないので使ったことはないですが 😅）
おわりに
以上、私が技術記事を書くうえで意識しているポイントを紹介しました！
少しでも、技術記事を書くあなたの参考になれば幸いです。
参考になる記事
Discussion