🧠

イシューからはじめる技術記事執筆術 ─ 不要な情報を削り、圧倒的な効率で価値ある技術記事を書く

に公開
メモ
読書
読書感想文
技術記事
idea

⚡️ TL;DR

『イシューからはじめよ――知的生産の「シンプルな本質」』の考え方を技術記事執筆に転用することで、「不要な情報」を削りつつ、価値の高い記事を効率よく書けるようにする話です。

💡 はじめに：なぜ技術記事にも「イシュー」が必要なのか

技術記事を書いていると、よくこんな状態になりがちです。

  • 「この技術も面白いし、あの検証も載せたい」
  • 「せっかく調べたから、関連情報も全部入れたくなる」
  • 「いろいろ調査した結果、自分の考えがブレてしまう」
  • 「気づくと章が増えすぎて、自分でも何が言いたいのか分からなくなる」
  • 「想定していた読者像と内容がずれてしまった」
  • 「生成 AI で情報を集めたものの、どうまとめればいいか分からない」

自分も技術記事を書くときに、
「あれもこれも入れたい」欲 に負けて、結果的に読みづらい記事になってしまったり、
無駄に長い記事になり、記事を書くこと自体に疲弊してしまうことが何度もありました。

安宅和人さんの『イシューからはじめよ――知的生産の「シンプルな本質」』を読んで、

と感じるようになりました。

この記事では、この本の考え方を技術記事の書き方に転用することをテーマにしています。

📚 『イシューからはじめよ』のキーワードをざっくり押さえる

本の内容をすべて説明するのは難しいので、
この記事で使うキーワードだけ、簡単に整理しておきます。

  • イシュー
    「今この瞬間、自分が時間を使って答えを出す価値のある問い」

  • イシュー度
    その問いに答えが出たときのインパクトの大きさ（人の行動・意思決定が変わるか？）

  • 解の質
    その問いに対して、どれだけ明確に・説得力のある答えを出せているか

  • 犬の道
    イシュー度が低い問いに、ひたすら量と根性で取り組んでしまうこと
    （がんばってたくさん書いたけど、読者から見ると「で、何が言いたかったの？」状態）

  • 知り過ぎたバカ
    イシューが曖昧なまま、ひたすら情報収集してしまい、本質を見失う状態

  • 仮説ドリブン
    「まず仮説を置き、それを検証する」という進め方
    （仮説なしでデータをいじり始めない）

  • アウトプットドリブン
    「最終的にどんなアウトプットにしたいか」から逆算して、分析や調査を設計する考え方

  • メッセージドリブン
    「読者にどんなメッセージを持ち帰ってほしいか」から文章を組み立てる考え方

  • 空・雨・傘
    「空」現状・問題提起 → 「雨」原因や構造の分析 → 「傘」それを踏まえた具体的な行動提案
    というストーリーの型

🎯 STEP0：誰の、どんな意思決定を助ける記事なのかを決める

読者・ゴール・記事タイプをざっくり決める

書き始める前に、ざっくり次の 3 つをメモしておくと、
後のイシュー（記事の核となる問い）の設定がかなり楽になります。

  • 誰に向けて書くか

    • 例: 駆け出し Web エンジニア / 3〜5 年目のバックエンドエンジニア / 自社の MLOps エンジニア など

  • 読み終わった読者が 何ができるようになっていてほしいか

    • 例: 「REST と gRPC のどちらを採用するか、自分の案件で判断できる」

  • 記事タイプ

    • 「〜をやってみた」（実装/導入レポート型）
    • 「俺の考える最強の〜」（意見/主張型）
    • 「〜について調査してみた」（調査/サーベイ型）
      など

ここまで決めてから、

「誰の・どんな意思決定のために、この文章を書くのか」

と一度言語化してみると、
次の STEP1 で定義する「イシュー」に自然とつながっていきます。

🔍 STEP1：イシューからはじめる ─ 本当に解くべき問いの見つけ方

本書でいう「イシュー」とは、

今この瞬間、自分が時間を使って答えを出す価値のある問い

でした。

技術記事に落とし込むと、

「この問いに答えが出ると、読者の技術選定・設計・行動が変わるか？」

という視点で問いを確認してみると、イシュー度を測りやすくなります。

良いイシューの 3 条件

記事のネタを思いついたら、次の 3 つを軽くチェックしてみると良さそうです。

  1. 本質的な選択肢を扱っているか

    • 「A か B か」「やるか・やらないか」といった
      構造的な分岐に関わる問いか？

    • 例:

      • 「REST API を継続するべきか、gRPC に移行すべきか？」
      • 「単一リポジトリにまとめるべきか、マルチリポジトリを維持すべきか？」

  2. 深い仮説があるか

    • 単に「使ってみました」ではなく、

      • 「多くの現場では X が重視されているけど、実は Y の方が本質的では？」
      • 「みんな I/O がボトルネックと言うけれど、本当のボトルネックはメモリ管理では？」
      • 「最近流行っている〇〇は、既存の △△ の“代替技術”になり得るのか？」

    • といった、常識を疑う／新しい構造で説明する視点を含められそうか。

  3. 記事の中で白黒（≒ スタンス）を出せるか（＝「解の質」を上げられそうか）

    • 数値実験・ログ・経験則・設計原則などを使って、

      • 「今回は A ではなく B を推す」
      • 「少なくともこの条件では、C はおすすめしない」

    • といった 一定の結論（解） まで到達できそうか。

    • ここでいう「解の質」は、

      • 結論があいまいではなく、
      • なぜその結論に至ったかが、読者にとって筋の通った説明になっているか
        といった「明確さ」と「説得力」のことを指しています。

この 3 つがすべて「はい」になっていると、
イシュー度が高く、不要な情報を足さなくても「読む価値のある記事」になりやすいと思います。

イシューは「疑問文」で書いておく

イシューを主語＋動詞を含む疑問文で書いておくと、
執筆中に迷子になりにくくなります。

  • 例（技術記事と相性の良さそうなもの）：

    • 「自分のチームが次に採用すべき API 方式は、REST と gRPC のどちらか？」
    • 「月間 1 億リクエスト規模のサービスで、マイクロサービス化は本当にペイするのか？」
    • 「イシュードリブンで技術記事を書くと、どの程度『不要な情報』を減らせるのか？」

こうやって日本語の 1〜2 行にしておくと、

「この記事のこの文章は、本当にこの問いに答えるために必要か？」

と自分に問いかけやすくなります。

イシューと記事タイトルは一致させるべき？

個人的には、

  • タイトル：読者がクリックしたくなる表現
  • イシュー：書き手の頭の中の“問い”そのもの

と考えると整理しやすいです。

完全に同じである必要はないけれど、

  • タイトルを読んだときに自然と想像される問い
  • 自分がイシューとして書き出した問い

がズレていないかだけ、軽く確認しておくと、
読者の期待と記事内容がズレにくくなりそうです。

「知り過ぎたバカ」にならないための情報収集

イシューが曖昧なまま、関連論文やブログを大量に読み始めると、
本でいう「知り過ぎたバカ」になりやすいです。

まずは、自分・チームの一次情報（実測値・障害事例・プロファイル結果・現場の会話など）から、

  • 「本当に解きたい問いは何か」
  • 「その問いに今答えを出すべき理由は何か」

をざっくり言語化してみてから、
足りない部分を二次情報で補うイメージのほうが、結果的に効率が良くなります。

🧩 STEP2：仮説ドリブン ① ─ イシュー分解とストーリーライン（空・雨・傘）

イシューが決まったら、

「この問いに答えるには、どんな要素を順番に見ていけばよさそうか？」

を分解していきます。

サブイシューに分解する（MECE をゆるく意識）

先ほどの例、

「次のプロダクトでは REST と gRPC のどちらを採用すべきか？」

をサブイシューに分解すると、例えばこんな感じになります。

  • サブイシュー 1: パフォーマンス・レイテンシの観点ではどうか？
  • サブイシュー 2: スキーマ管理・変更容易性の観点ではどうか？
  • サブイシュー 3: クライアント実装・言語サポートの観点ではどうか？
  • サブイシュー 4: チームの習熟度・運用体制の観点ではどうか？

このくらいの粒度まで分けておくと、
それぞれに仮説を立てて検証するイメージが持ちやすくなります。

「空・雨・傘」で記事の骨組みを作る

本で紹介されている「空・雨・傘」の型は、技術記事にもそのまま使えます。

  • 空（現状・課題の共有）

    • どんな背景・モヤモヤから、このイシューが生まれているか？
    • 例：REST は十分に動いているが、スキーマ管理や高速化で限界感が出てきた、など。

  • 雨（分析・検証）

    • サブイシューごとに仮説を立てて、データや経験から検証するパート。
    • 例：レイテンシの比較結果、スキーマ変更の手間、チーム熟練度の違いなど。

  • 傘（結論・提案）

    • 「こういう条件なら gRPC のほうが合理的」「こういう制約なら REST を維持した方がよい」など、
      読者の意思決定に直結する提案を書く。

この型に沿って見出しを決めていくと、

  • 「やってみた報告」で終わらず
  • 「だからあなたはどう選べばよさそうか」まで自然と書きやすくなります。

3 つのよくある記事タイプを「空・雨・傘」に載せてみる

技術記事でよく見かける 3 パターンを、ざっくりマッピングするとこうなりそうです。

  • 「〜をやってみた」記事

    • 空：なぜその技術を試そうと思ったのか（既存の何がつらかったのか）
    • 雨：既存案 vs 新案の比較・検証
    • 傘：どういう状況なら導入をおすすめできるか／しないか

  • 「俺の考える最強の〜」記事

    • 空：世の中の「定番」のやり方、その限界や失敗パターン
    • 雨：なぜその限界が生まれるのか、どんな構造的問題があるのか
    • 傘：自分が提案する「最強の〜」の設計と、その適用条件

  • 「〜について調査してみた」記事

    • 空：どんな意思決定のために、この調査が必要なのか
    • 雨：選択肢 A/B/C の比較や業界動向の整理
    • 傘：現時点での結論と、「今はこうしておき、1 年後にここを見直す」といった具体的な方針

📊 STEP3：仮説ドリブン ② ─ 絵コンテとしての図表・検証設計

ストーリーラインができたら、次は 「どんな図や表が載っていたら読者が納得しやすいか」 を先に考えてみます。

分析は「比較・構成・変化」のどれかに落とす

本では、定量分析が次の 3 パターンに整理されています。

  • 比較：A と B はどちらがどれくらい良いか？
  • 構成：全体のうち、どの要素がどれくらいを占めているか？
  • 変化：時間や負荷に応じて、どう変わっていくか？

技術記事だと、例えばこんなイメージです。

  • 比較：REST vs gRPC のレイテンシ、フレームワーク A vs B の CPU 使用率
  • 構成：レスポンスタイムのうち、DB/アプリ/ネットワークが占める割合
  • 変化：**QPS（Queries Per Second：1 秒あたりのリクエスト数）**を増やしていったときのスループットやエラーレートの推移

「この記事ではどのパターンの図を使いそうか？」を先に意識しておくと、
後から数字を集めるときにも迷いにくくなります。

「この図があれば納得できる」という絵コンテを先に作る

ポイントは、

「どんなデータが取れるか」ではなく、
「どんな図が載っていたら読者は納得できるか」から逆算する

ことです。

例えば：

  • X 軸：同時接続数
  • Y 軸：p95 レイテンシ
  • 比較する線：REST / gRPC / gRPC + 圧縮
  • 伝えたいメッセージ：
    「この負荷領域では、そもそもプロトコルより DB が支配的」

のように、ざっくりしたラフを先に決めておくイメージです。

データ取得方法まで文章で書いておく

図のイメージが固まったら、

  • どのツールを使うか（例：wrk, k6, 自前のロードツールなど）
  • どのような条件でテストするか
  • どの値をログから抜くか

といった 「実現方法」も軽くメモしておく と、
実際に検証を始めたときに手戻りが少なくなります。

🚀 STEP4：アウトプットドリブン ─ 犬の道を避ける検証の進め方

絵コンテができたら、いよいよ手を動かすフェーズです。

本では、

「頑張って量をこなす」犬の道ではなく、
イシュー度の高い仮説から検証していく

ことが大事だとされています。

バリューの高いサブイシューから検証してみる

REST vs gRPC の例で考えると、

  • 「本当にパフォーマンスが改善するか？」

が崩れると、記事のストーリーがそもそも成り立たなくなります。

なので、

  • まずはパフォーマンス比較の図から作りにいく
  • その後で、開発体験や運用の話を検証していく

という順番にすると、手戻りが少ない進め方になりやすいです。

データに素直に従い、ストーリーを修正する

実際にやってみると、仮説が外れることも普通にあります。

  • gRPC にしたのに、思ったほど速くならない
  • むしろトレースや監視が複雑になり、運用コストが跳ね上がった

こういうときは、

  • 「最初にこういう仮説を立てていた」
  • 「検証した結果、ここが崩れた」
  • 「そこから見えてきた、本当のボトルネックはこれだった」

という流れでストーリーを書き換えていくと、
読者にとっても「仮説の立て方〜検証〜アップデート」のプロセスが見えやすくなります。

完成度より「回転数」を重視してみる

完璧なベンチマークや網羅的な調査を目指すと、一生公開できません。

  • まずは 70〜80% の確信が持てたタイミングで、一度書ききる

  • そのあと、

    • 追試した結果を追記する
    • 読者のフィードバックを受けて更新する

という「回転率の高い」進め方を意識してみると、
本の言う「アウトプットドリブン」に近い形で記事の質を上げていけそうです。

💬 STEP5：メッセージドリブン ─ 伝わる記事に仕上げる

最後に、分析結果を読者にとってのメッセージに整理していきます。

メインメッセージは 1〜3 個に絞る

例えば REST vs gRPC の記事なら、メインメッセージはこんなイメージかもしれません。

  • メッセージ 1：レイテンシ改善を狙うなら、まずは DB とキャッシュ設計を見直すべきであり、プロトコル選定はそのあとでも十分なケースが多い
  • メッセージ 2：gRPC が真価を発揮するのは、〇〇 のような条件を満たすとき
  • メッセージ 3：チームの習熟度と運用コストまで含めて考えると、スタートアップの初期段階では REST のほうが合理的なケースが多い

「読者に覚えて帰ってほしいポイント」が 1〜3 個にまとまっていると、
それ以外の部分で削ってもよさそうな説明も見えやすくなります。

エレベーターテストに通るリード文を書く（TL;DR でも OK）

本で紹介される「エレベーターテスト」は、
技術記事のリード文や TL;DR にそのまま使えそうです。

仮に自社の CTO にエレベーターで 30 秒だけ捕まえたとき、
この記事の結論を説明できるか？

を基準に、

  • イシュー（問い）
  • 結論（ざっくりでよい）
  • 読者が得られるもの

を 1〜2 段落にまとめてみると、それがそのまま：

  • 記事冒頭のリード文としても使えるし
  • 「TL;DR」や「この記事のポイント」といった見出しの下に箇条書きで置く

といった形でも使えます。

図表は「1 チャート 1 メッセージ」を意識する

図や表については、

  • パッと見て 3〜5 秒で「何が言いたいか」がわかるか？
  • その図は、どのメッセージを支えるために存在しているか？

を軽くチェックしてみると、
「ただの情報の寄せ集め」になっていないか確認しやすくなります。

もし 15 秒眺めても意味がわからない図があったら、
分割するか、削るかを検討してみてもよさそうです。

📌 付録：よくある技術記事パターンのイシュードリブン・テンプレ

「〜をやってみた」（実装/導入レポート型）
**典型イシュー例**

- 「既存の構成 X では Y という課題があるが、新技術 Z はそれをどの程度解決できるか？」
- 「ライブラリ A を導入することで、開発体験とパフォーマンスのどちらをどの程度改善できるか？」

**見出しテンプレ**

# [技術名] を導入してみた結果、[どんな課題] はどこまで解決できたか？

## 空：なぜ [技術名] を試そうと思ったのか

- 既存構成・ライブラリ
- 具体的に困っていたこと（レイテンシ/コスト/運用負荷 など）

## 雨：既存構成 vs 新構成をどう比較・検証したか

- 検証環境・条件
- 比較観点（パフォーマンス/開発体験/運用）
- ベンチマークやログの結果

## 傘：どんな条件なら [技術名] の導入をおすすめできるか

- この条件なら導入する価値がある
- この条件ならやめておいたほうがいい
- 導入時に気をつけるべきポイント

**ポイント**

- 「動きました」で終わらせず、必ず **「何と比べてどうだったか」** を書く。
- イシューは「導入できるか？」ではなく「導入すると何がどれくらい変わるか？」に置いてみると、不要な情報が自然と削りやすくなります。
「俺の考える最強の〜」（意見/主張型）
**典型イシュー例**

- 「〇〇という条件のもとで、どのようなアーキテクチャが最もバランスが良いか？」
- 「現場でよく推される設計パターン A は、本当に最善と言えるのか？」

**見出しテンプレ**

# 俺の考える最強の [対象] ─ なぜこの構成に落ち着いたのか

## 空：よくある「定番」のやり方と、その限界

- 世の中でよく見かける構成やプラクティス
- 実際に現場で遭遇したつらみ・失敗パターン

## 雨：何が本当の問題なのか？構造を整理する

- ボトルネック・トレードオフの整理
- 「定番」がうまくいかない背景にある構造的な理由

## 傘：自分が採用している「最強の [対象]」の設計と適用条件

- 推している構成・ルール
- それが刺さる前提条件（サービス規模/チーム構成など）
- 逆に、この条件なら別の選択肢を取るべき、という線引き

**ポイント**

- 「好み」を語るだけでなく、
  **「どんな構造を見た結果、その結論に至ったのか」** をセットで書くと、読者が自分の文脈に当てはめやすくなります。
「〜について調査してみた」（調査/サーベイ型）
**典型イシュー例**

- 「今後3年間を見据えて、我々のサービスにとって採用候補になりうる DB はどれか？」
- 「新たな脆弱性 X は、自社サービスにとってどの程度の実害リスクを持つか？」

**見出しテンプレ**

# [技術/トピック] を調査してみた ─ 今の自分たちは何を選ぶべきか？

## 空：この調査は、どんな意思決定のために必要なのか

- どんなプロジェクト・サービスに関わる話か
- どんな選択を迫られているのか（A か B か、導入か見送りか）

## 雨：選択肢の整理と比較

- 選択肢 A/B/C の概要
- 比較観点（機能/コスト/運用/将来性 など）
- 一次情報・信頼できる情報源の整理

## 傘：現時点での結論と、今後の見通し

- 今の自分たちの状況なら、どの選択を推すか
- 今後1〜2年で見直すべきポイント
- まだ決着がついていない論点と、ウォッチすべき動き

**ポイント**

- 「調査した結果、こういう特徴がありました」で終わらせず、
  **「だから今はこうしておく」** というスタンスを1行でも書いておくと、記事のイシュー度がぐっと上がります。
トラブルシュート／障害対応記録（ポストモーテム型）
**典型イシュー例**

- 「本番で発生した障害 X の根本原因は何で、再発を防ぐには何を変えるべきか？」

**見出しテンプレ**

# 本番障害 [概要] をどうやって潰したか ─ 根本原因と再発防止のための設計

## 空：どんな障害が、どんなインパクトで起きたか

- 障害の概要・影響範囲
- 表に出た症状（ユーザーから見える現象）

## 雨：原因特定までの仮説と検証のプロセス

- 最初に立てた仮説
- 実際にやったログ解析・トレース・切り分け
- 仮説が外れたポイント・学び

## 傘：根本原因と、再発防止のための設計・運用の変更

- 真のボトルネック・構造的な問題
- 具体的に変えたコード・アーキテクチャ・運用ルール
- 他の現場にも通用しそうな学び
アーキテクチャ解説・設計意図の共有（設計解説型）
**典型イシュー例**

- 「なぜ自分たちは、このサービスでこのアーキテクチャを選んだのか？」
- 「こういう制約のもとで、どのようにシステムを分割するのが妥当か？」

**見出しテンプレ**

# [サービス/システム] のアーキテクチャ解説 ─ この構成にした理由とトレードオフ

## 空：サービスの背景と、解決したかった課題

- ドメイン・トラフィック・非機能要件
- 特に重視したい品質（可用性/変更容易性/コストなど）

## 雨：候補アーキテクチャとトレードオフの整理

- 候補となった構成案 A/B
- 各案のメリット・デメリット
- 最終的に今の構成に決めた理由

## 傘：このアーキテクチャを採るべき/避けるべき条件

- こういう前提ならおすすめできる
- こういう場合は別の選択肢を検討したほうがよい
- 今後見直す可能性のあるポイント

おわりに

『イシューからはじめよ』のメッセージを、
技術記事にだけギュッと絞って雑にまとめると、

「どの問いに答えるか」をちゃんと決めてから書き始めると、
不要な情報を削って、効率的に価値のある記事を作成しやすくなる

という話だと感じています。

  • イシューが曖昧なまま書き始めると、
    「あれもこれも入れたい」→「蛇足だらけ」→「結局伝わらない」
  • イシューを 1 行の疑問文で言語化してから書き始めると、
    その問いに答えるために 本当に必要な情報だけ が残り、効率よく価値ある記事に仕上がる

この記事が、Zenn や社内ドキュメントで記事を書くときに、

  • 「まずイシューを書き出してみるか」
  • 「この段落は本当にイシューに効いているか？」

と一瞬立ち止まるきっかけになったらうれしいです。

おまけ：イシュードリブン思考と 生成 AI はかなり相性がいい

この記事の本筋とは少し外れますが、イシュードリブンに記事を書こうとすると、
生成 AI（ChatGPT など）との相性もかなり良くなると感じています。

イシュードリブンで進めると、自然と最初にこういった情報が言語化されます。

  • イシュー（この記事で答えたい問い）
  • 想定読者
  • サブイシュー（分解した論点）
  • 大まかなストーリー（空・雨・傘）
  • 欲しい図・表のイメージ（絵コンテ）

ここまで決まっていると、そのまま 生成 AI へのプロンプト に落とし込みやすくなります。例えば：

  • 想定読者：3〜5 年目の Web エンジニア

  • イシュー：次のプロダクトで REST と gRPC のどちらを採用すべきか？

  • サブイシュー：レイテンシ / スキーマ管理 / チームの習熟度

  • 空・雨・傘：

    • 空：REST で感じている限界
    • 雨：REST vs gRPC の比較
    • 傘：どういう条件なら gRPC を選ぶべきか
      こういう前提で、見出し案と各セクションで押さえるべき論点を整理してほしい

といったお願いがしやすくなります。

逆にイシューが曖昧なまま、

「REST と gRPC の違いを教えて」

のように聞いてしまうと、本当に欲しいものと微妙にズレた長文が返ってきがちです。

ざっくりまとめると、

  • 人間側：イシューと絵コンテ（構成・図のイメージ）を決める
  • 生成 AI 側：情報収集の整理や文章のドラフト・言い回しの改善を手伝ってもらう

という役割分担がしやすくなります。

Discussion