わかりやすい技術解説記事を作るには 脆弱性解説を例に(2025年ver.)
この記事を作ったきっかけ
最近、ありがたいことにYouTubeの方でもわかりやすいと評判の声を多くいただき、
また様々な場所でアドバイスを聞かれたり、資料などのレビューをする機会も増えてきました。
以前 人にわかりやすく物事を伝える - くれなゐの雑記
という記事を書きましたが、改めて現時点でどうやって資料を作るべきか言語化しておこうと思い、筆を取ることにしました。
またここでは「記事」という言葉を使っていますが、もちろん動画やスライドなどでも同様です。
解説記事の大目標
物事を解説するうえでの最終的なゴールは、受け手の疑問に答えることです。
解説記事においては、受け手がわからない事があった上で見に来ているわけですから、それに答えることを期待されているわけですね。
疑問に対してスッキリとした答えがわかったとき「わかりやすい」と思われると自分は考えています。
以前作った React2Shellの動画 では、「React2Shellでどういう原理で発生しているの？」という受け手の疑問に答えるべく作成しました。
ここで、記事を作る上でのポイントは以下の3つです。
- タイトルに受け手の疑問を書く
- 記事の中でその疑問の答えを書く
- 受け手が内容の正しさを確認・納得できるものを書く
React2Shellを例に考えてみましょう。以下も正しい形の一つです。
- React2Shellはなぜ影響するのか
- 安全でないでシリアライゼーションをするから
- なぜ正しいか: Amazonが言ってるから (React2Shell 脆弱性 (CVE-2025-55182) に対する中国関連脅威アクターの活発な悪用活動 | Amazon Web Services ブログ)
確かに正しいことを言っていますが、あなたがこういう記事を見たら「うーん？いやそうなんだけど」ってなりますよね。
求められている答えを作るためには、その疑問を持った背景、そこにアクセスしに来た理由を理解する必要があります。
例えば受け手が「どういう条件だったら脆弱性が刺さるのか正確に理解したい、そのために原理を知りたい」という背景を持っていたらこの答えは不足していますよね。ではどうすれば背景を理解できるのでしょうか？
step1: 疑問の背景を理解する
疑問の背景を理解するためには、解説している知識がどう使われるかイメージすることが大切です。
とはいえ、イメージするための銀の弾丸的なものはありません。
こういうときに役に立ちそうだな、こういうところで困ってそうだな、みたいなものをイメージする以外私は知りません。
そして、そういう勘所はいろんな人とコミュニケーションをして困っていることを聞き出す、
いろんな実務経験を積む事が重要だと思っています。
日頃のコミュニケーションや実務でこういう「人の気持を理解する」という技術を身につけていくわけですね。
脆弱性の詳細を解説することに限って使える「背景」の例をここに共有しておきます。
自分は脆弱性を解説する時、これらの背景を持った人という想定で作っています。
step2: なぜ自分の記事を見に来たのか意識をする。
おそらく多くの人は一次情報に近いところを参照するわけで、個人で書かれた二次情報は基本信頼しないことが前提です。
ではなぜ人々は記事を見に来るのでしょうか？
それは一次情報だけではわからないことがあるからです。
逆に言うと、一次情報で書かれている内容をそのまま伝えるだけでは、ただ信頼性を落としているだけなので全く意味がありません。
個人で解説記事を書く者は、何かしら付加価値をつけなければなりません。
日本語に存在しないから日本語で解説する、世の中で説明されていない領域まで深く解説する、動画にするとわかりやすくなるので動画にしてみるなど。
あくまでも自分自信は信頼に足らない二次情報だということを意識した上で、どういう付加価値をつけるべきなのかを考えてみましょう。
自分の場合は以下のような付加価値を意識しています。
一方で、厳密な説明は避けています。なぜならばあくまでも二次情報なので、最終的には一次情報をそのまま読んで理解してもらうことを想定しているからです。
Zerologonの動画 はかなりそれを意識しています。
step3: 疑問に対する答えと、視聴者が納得するような根拠を述べる
さて、視聴者の背景、疑問も理解したことですし、それに応じた粒度感で説明していきましょう。
React2Shellの動画では6:00 あたりのところで答えていますね。それ以降の部分はすべて「根拠」です。
step2で言及した通り、我々は信頼に足らない二次情報なので、根拠を述べる必要があります。
そして、ややこしいことに、答えと根拠は「確度」を持ちます。
脆弱性を例に、以下のシチュエーションを考えてみましょう。
- 実際に攻撃が刺さっている動画が公開されている。PoCも公開されている。
- そのライブラリ等を提供している公式が脆弱だと言っている
- KEVCに乗っている
- Microsoft、Google、Amazonなどの信頼できる大企業が対応しろといっている
- 知らないけど大企業そうなセキュリティベンダーが言及している
- 知らない人がXで危険な脆弱性があると言及している
- 信頼できる技術者がこの脆弱性は危ないと言及している
- 日頃から大したことない脆弱性をおおごとに取り上げている人が今日も取り上げている
イメージしてみると危なそうなやつとそうでもなさそうなやつに分かれるかなと思います。
更にややこしいことに、「納得」するために乗り越えるハードルも人によって異なります。
我々はできる限り多くの人に納得してもらいたいので、複数の根拠を使い分けてうまく説明します。
あなたは記事に付加価値をつけなければなりませんが、そこは残念ながら「信頼できる情報源が言っている」というテクニックは使えません。
どうやったら証明できるか？ですが、これも銀の弾丸はないので、技術の見せ所になります。
自分が意識していることを以下に書きます。
- デフォルトの環境を用意して刺さったらデフォルトの環境で刺さることは保証できる。それ以外で証明できない部分は個人の推測の域になる。
- コードベースのトレースはすべて個人の推測の域になる。デバッガを刺してリクエストを通した場合、そのリクエストにおいてのその変数はその状態になることが、デバッガによって挙動が変わらない限りは保証できる。
基本的には動作したもの以外は保証しないという前提で、後は「自分の推測」という確度で説明しています。
ただし、「自分が推測した理由」を述べ、それを受け手が納得してもらった場合は「信頼に足る情報」として取り扱ってもらえるかもしれません。
step4: さらなる疑問をイメージする、それに答える
残念ながら、「疑問、答え、根拠」は一回の説明では終わりません。疑問は再帰的に発生します。
React2Shellの場合、例えばReactに詳しくないセキュリティエンジニアやSOCなどがいた場合、「どういうところで使われてるの？」「なんでフロントエンドのライブラリでサーバーサイドのRCE？」というのが気になるでしょうし、「こういうフローで脆弱性が発生します」と説明した場合も、「じゃあそのフローって本当に正しいの？」という疑問に対して答えなければなりません。
できる限り多くの人に聞いてもらいたくはありますが、あらゆる人の疑問に答えるとやはり内容が散らかってしまいます。
そこで、皆興味がある内容を前に持ってきて、興味のある人が少ないような内容を後ろに持っていくことで、万人に満足してもらえる物を作ります。
どこかで興味のない内容があると、そこで離脱してしまいますから。
まず、関連するあらゆる疑問を洗い出した後、それを構造化していきます。優先するべき事項は
- 解説したい内容の全体像
- 説明するのにどうしても必要な前提条件
で、そこから掘り下げていきます。なぜ先に全体像を説明するのかと言うと、受け手にとって「興味がある内容がそこにふくまれているのか、どこにあるのか」ということが一番最初の興味のある内容だからです。
そしてそれがあることがわかった聞き手は、「その知識を得るためには何が必要なのか」ということを知るために、前提条件が知りたくなるからです。
「最初にあなたの興味はこのルートをたどるとわかりますよ」「あなたはまずこれを知る必要がありますよ」ということを示すことで、受け手は話をようやく聞いてくれるわけです。
ただし、全体像を伝えるうえで、どうしても中身が理解できていないと説明が難しい箇所が出てきます。その際の方法を説明します。
step5: 全体像を説明するうえでのテクニック
大体の物事は木構造のような形で構造化して説明することができます。本の目次がそうなっていますね。章、節、項のように。
しかし全体像を見せたタイミングで、大量の「知らない用語が出てきた」「これは何？」「本当に正しいの？」という疑問が発生します。
その疑問の羅列こそが説明する記事で解決する課題であり、「タイトルに設定した疑問」を掘り下げた結果なのです。
全体像を説明するコツは、「この記事を読むうえで知っていなければならない情報」と「これから説明する情報」を明言しつつ、専門的な内容はわからなくても 気持ち を伝えることです。
この気持ちを伝えるというのがなかなか公式ではやりづらく、あなたの記事を読む理由のうちの一つになります。
ここはセンスですね。
React2Shellの動画では6:00 この動画のここを見てください。「ヤバいリクエスト」みたいな言葉を意図的に使うことで、ここはまだ知らなくてもいいんだなということを示しつつ、何となく全体像を示すことができているかなと思います。
そして出てきた疑問たちを体系化し、どのような順序で説明するかを受け手に示すことで、受け手は安心して記事を読むことができるのです。
それでも安心できない人で、救えない人は切り捨てちゃいましょう。
ただ、不用意に切り捨てることのないよう、「知識ツリー」のようなものはイメージしたほうがいいです。
step6: 知識ツリーを意識する
全体像を設計するうえで、受け手の前提知識をしっかりと把握する必要があります。
そこで、「この知識を知っているのであればこの知識は知っているはず」という知識ツリーを自分の中で定義し、考えています。
例えばheap exploitationを知っている人は、おそらくStack overflowも知っているはず、楕円曲線暗号を知っている人はRSAを知っているはず、といった想定ができることが多いと思います。
そのツリーの開始地点と終了地点を定義し、知っている内容を省略しつつ、知らない内容がふくまれる場合はそれを説明する、といったことが必要です。
例えばカーネルの脆弱性の話をしているときに、pipeを知らない前提で話しているのに、ページングのことを知っている前提で話すのはおかしいですよね。
こういった余分な知識の不整合を減らすことで、無駄な離脱を減らすことができます。
一定切り捨てるのは仕方ながないですが、意味のない説明をして無駄に時間をかけて、本来救える人たちを救えないみたいなことは避けるようにしましょう。
さて、全体像を書けました。それでは具体的な内容を書いていくうえでの大切で難しい注意事項です。
step7: 嘘を書かない
内容に嘘があると、簡単に人は離脱してしまします。
「sha256で暗号化する」みたいな事が書いてあっただけで自分は記事を閉じてしまいますね。
こういったものは離脱の原因です。
受け手は「知らないことを聞きに来る」だけではなく、同時に「知っていることが正しく説明されているか確かめる」ことをして記事の正確性を見定めています。
したがって、我々は正確に記事を書かなければ読んでもらえません。
嘘を書かないことは難しいですが、以下を意識することで良くなります。
- 一次情報から正しく引用する
- 二次情報から引用する際は二次情報であることを明記しつつ、正確でない可能性も言及する
- わからないことはわからないと言う。推測であることは推測であると言う
- 証明できたことは、証明できたスコープで正しく説明する
- 用語は正しく使う、常に辞書や公式ドキュメントを引くつもりで、常に言葉の正しさを疑う
自分の動画 を見てもらうと、「こう思う」「僕はこう考えている」「少なくともこの条件は必要」など、自分の推測と、確認できた範囲でだけ言及することに気をつけていることがわかるはずです。
変に一般化せず、わかったことだけ、できるだけ狭いスコープで言うことで嘘を回避できます。
また、「公式ドキュメントが言っているから正しい」というスタンスなのではなく、「公式ドキュメントがこう言っているので正しいと思われる」といったスタンスがちょうどよいかなと思います。
なぜならば、「公式ドキュメントに記載がある」という部分は事実あり、信頼できる情報源が言っているので確度が高いのもそうだが、内容が正しいかどうかはわからないからです。したがって、「公式ドキュメントが言っている」という事実を一度伝え、次にその確度を伝える形が正しいです。
脆弱性の場合、本当に証明できるのは脆弱性が刺さったときだけです。あとは少量なりとも推測が混じります。その推測が無視できるレベルなのかどうかは各々が判断する必要があります。
さて、読み手視点で考えるとこんな辛いことをしないといけません。
気をつけているとはいえ、嘘を言ってしまうことは当然あります。それで叩かれるかも。
これではモチベーションが続きませんね。どうすればいいのでしょうか。
step8: 書き手のモチベーション
今までは読み手にとってどういったメリットがあるのか説明してきましたが、自分の事例を元に書き手側のメリットを紹介しましょう。
自分の場合は「世間からの信頼を高まった」と感じています。
最初はおそらく誰からも注目されていませんでしたが、少しずつ「信頼に足る」と評価されてきているのかなと感じています。
だからこそ動画を出したら安心して見てもらえますし、「kurenaifの言っているからこの内容は正しい」と少しでも思ってもらえてるのかなと感じています。
これはstep3で登場した「信頼できる根拠」に「kurenaif」が少しでも近づいているのかなと推測しています。
もしそうなれば責任を伴うでしょうし、責任を伴うということは新たな役割が与えられたと思えるのかなと考えています。
役割があると、自分って生きてて良かったなと思えますし、貢献できている感覚があってやりがいも感じます。
またSECCONや様々なセキュリティエンジニアとの繋がりもでき、それによって新たな学習機会も得ることができます。
なんか拡大再生産的で楽しいですね。
これからの生成AI時代、ブログ記事等を見に行かなくても、ChatGPTやGemini,Claudeなどがそれらをまとめていい感じに出力してくれるでしょう。
それらのAIは読み手を満足させるために、「疑問」「答え」「根拠」を整理して述べてくれるでしょう。
ハルシネーションリスクがあるとはいえ、生成AIよりも信頼できないような物はこれからもっと見られなくなっていくと思います。
これからは生成AIが出力できないようないい記事を書けないと生きていけません。
今は動画も簡単に作れますしねｗ
どれだけ対抗できるかはわかりませんが、生成AI時代でも生き残れるアウトプットをこれからも作るために、
安心して読める、嘘の少ない誠実で正しい記事をこれからも作れり、生成AIより信頼できるよう頑張りたいですね。
ところで個人的にはこういったアウトプットができる人材は希少だと思っています。
まだまだやりたいことはたくさんあるので、自分と一緒にこういう活動ができる人を募集しています。
魔女のお茶会 なんかもいかがでしょうか？
