技術記事の書き方：複雑な概念をわかりやすく伝える表現、たとえの選び方と例の設計
1. 技術記事に層分けが必要な理由：一つの概念、三種類の読者
B2B技術記事の読者は決して一人ではありません。同じ「構造化データマークアップ」というテーマでも、CFOはこれで問い合わせが増えるのかを知りたがり、CTOは改修にどれだけ工数がかかるのかを知りたがり、エンジニアはJSON-LDのフィールドをどう書くのかを知りたがります。三種類の人に同じ文章を読ませるのは、誰にも理解されないのと同じです。
層別ライティングの核心は、各層が独立して成立することです。意思決定者はコードを読まなくてもやる価値があるか判断でき、エンジニアは論文を読まなくても実現可能性を判断でき、実装者はデフォルト値を推測しなくても作業を始められます。これはGEO コンテンツの階層化の考え方と一致します。事実、意見、約束がそれぞれの場所に収まり、AIが抜き出すのは事実の層です。
| 読者角色 | 関心のあること | 対応する層 | 書くべきでない内容 |
|---|---|---|---|
| 意思決定者（CXO、購買） | 投資する価値があるか、リスクはどれくらいか | たとえの層 | コード、数式、パラメータ表 |
| 技術責任者（CTO、アーキテクト） | 実現可能性、工期、境界 | 例の層 | 基礎概念の過剰な解説 |
| 実装者（エンジニア、運用） | フィールドの記入方法、デフォルト値 | 数式の層 | 漠然とした「最適化を推奨」 |
これが技術記事でE-E-A-Tを築く方法でもあります。専門家の層では正確なパラメータを示し、意思決定者の層では誠実な判断を示し、どちらの層でも知ったかぶりをしません。信頼性シグナルの構築方法はE-E-A-T：B2Bコンテンツの信頼性シグナル。
2. たとえの選び方：著者の業界ではなく、読者の業界を使う
たとえは技術ライティングで最も誤用されやすいツールです。良いたとえは非技術系の読者に10秒で概念を理解させ、悪いたとえは誤ったメンタルモデルを持たせたまま去らせ、後から訂正する暇もありません。
たとえ話を選ぶ第一の原則は「読者がよく知る場面を使う」ことで、「書き手がよく知る場面を使う」ことではありません。製造業の読者に API を説明するなら、レストランのメニューではなく、生産ラインの作業ステーション間のコンベアでたとえましょう。SaaS の読者に CDN を説明するなら、宅配倉庫ではなく、オフィスの受付でたとえましょう。読者の仕事の日常こそが、最高のたとえ話の引き出しです。
| 技術概念 | よくある誤ったたとえ | 正しいたとえ（業界別） | 誤解を招くリスク |
|---|---|---|---|
| API インターフェース | レストランのメニュー | 生産ラインの作業ステーション間のコンベア | メニューは選択を強調し、コンベアは非同期を強調する |
| CDNキャッシュ | 宅配倉庫 | オフィス受付のファイルキャビネット | 倉庫は物流を強調し、受付は手近に取り出せることを強調する |
| JSON-LD | 製品マニュアル | 検索エンジン向けの身分証明書 | マニュアルは詳細さを強調し、身分証明書は項目の標準を強調する |
| リトライ機構 | 電話のかけ直し | 生産ラインの故障時の自動復帰 | 電話のかけ直しは人を強調し、自動復帰は自動化を強調する |
場面に即した例：ドイツの自動車部品メーカーの顧客に Web Vitals の LCP 指標を説明するとします。「LCP とはページが開く速さのことです」と言ってはいけません。これは同語反復です。
「LCP とは、ユーザーがメイン画像を実際に見られるようになるまでの時間です。生産ラインの重要ステーションのランプが赤から緑に変わるまでの時間と同じで、2.5 秒を超えるとライン全体が止まってしまいます」と伝えましょう。このたとえは技術的なしきい値と顧客の日常業務を結びつけるので、意思決定者はすぐに判断できます。
たとえ話の一線は、それが「何であるか」にしか答えず、「どう計算するか」には答えないことです。たとえが数値の関係を説明するために使われ始めると、誤解を招きます。たとえば帯域幅を「水道の蛇口」でたとえると、読者は通信が連続的だと思い込みますが、実際のネットワークはパケット単位です。こうした箇所ではすぐに例の層に切り替えなければなりません。
三、例の設計：最小限で動く、5 分で試せる
例は飾りではなく、技術記事で最も説得力のある部分です。動く 3 行のコード例は、千字の概念説明に勝ります。しかし、例の書き方が悪いと逆効果になります。おもちゃのような例は境界条件を覆い隠し、エンジニアにあなたの方案が本番環境でもこんなに簡単だと思わせてしまいます。
良い例の基準は、入力が何か、出力が何か、読者が自分の環境で 5 分以内に試せることです。コードは 3 行以内、依存は 2 つ以内、環境の前提は例の冒頭に書きます。Docker のインストールやクラウドアカウントの登録、30 分走らせないと結果が見えない例は、良い例とは言えません。
| 例の種類 | 適用層 | 規模の基準 | 必ず含めるもの |
|---|---|---|---|
| 概念の示意 | たとえの層 | 一段の文章または一枚の図 | 日常の場面 + 対応関係 |
| コードスニペット | 例の層 | 10 行以内 | 入出力 + コメント |
| 設定例 | 例の層 | 完全に貼り付け可能 | デフォルト値 + コメント説明 |
| 境界条件 | 数式の層 | 表またはリスト | 異常入力 + 処理方法 |
| 性能データ | 数式の層 | 数値表 | 環境、サンプル数、繰り返し回数 |
場面別の例：構造化データ Schema の Article マークアップを解説するとき、JSON-LD のブロックを1つ貼るだけで済ませてはいけません。良い書き方は、まず name、author、datePublished の3行だけの最小例を示すことです。
次に境界条件の表を付けます。記事に著者署名のフィールドがない場合はどうするか、転載記事の場合はどうするか、日付は UTC かローカルタイムゾーンか。エンジニアはこの表を読めば、どんなケースで Search Console の警告が出るか分かります。
直感に反する点：「簡潔にするためエラー処理は省略しました」と例に書くのは、技術記事で最もよくある自己欺瞞です。読者はエラー処理を省いてくれたことに感謝しません。あなたが省いたその穴を本番環境で踏みます。正しいやり方は、例の中に TODO コメントを1つ残し、「本番環境ではリトライとタイムアウトを追加」と書くことです。一言で十分です。
四、数式とパラメータ：デフォルト値を示し、読者に推測させない
実装者が技術記事を読むときに最も怖いのは、数式はあるのにデフォルト値がないことです。パラメータをどこから調整すればいいか分からず、勘に頼るしかありません。技術記事の数式の層では、各変数の単位、デフォルト値、調整範囲をすべて明記する必要があります。
AI と協力して技術記事を書くとき、このステップが最も省略されがちです。大規模モデルは概念の説明は得意ですが、本番レベルのデフォルト値を示すのは苦手です。人によるレビューでこの層を必ず補う必要があります。どのパラメータを人が検証すべきかは、次を参照してください。コンテンツ制作におけるAI協働の境界線。
| 項目の種類 | 必ず書くべきフィールド | 例（LCP を例に） |
|---|---|---|
| しきい値 | 合格ライン、要改善、不合格 | 2.5秒以下が合格、2.5〜4秒が要改善、4秒超が不合格 |
| 初期値 | 初期値とよくある調整の方向 | 画像の遅延読み込みはデフォルトで有効、ファーストビューの画像は遅延読み込みしない |
| 測定環境 | デバイス、ネットワーク、サンプル数 | 4G ネットワーク、Moto G Power、75パーセンタイル |
| 単位 | ミリ秒か秒か、パーセントか小数か | CLS は0〜1の小数を使い、パーセントは使わない |
データの出典を明記することは、この層の必須要件です。引用するしきい値やデフォルト値はすべて、公式ドキュメントか再現可能なテストにたどれなければなりません。情報源管理の方法は次を参照してください。情報源管理：専門家インタビュー、データ引用、出典の明記。出典のない数字は、専門的な読者なら一目で見抜きます。記事全体の信頼性にも影響します。
五、落とし穴：技術ライティングでよくある4つの事故
| よくある誤り | パフォーマンス | 結果 | 修正アクション |
|---|---|---|---|
| 分野をまたいだたとえ | 小売の場面で産業用 API を説明する | 読者の30%が誤解する | 読者の業界に合わせたたとえに変える |
| 例の過度な簡略化 | 「エラー処理は省略」 | 本番環境で穴を踏む | TODO コメントを残すか境界条件の表を補う |
| 数式だけ貼ってデフォルト値を示さない | 変数が宙に浮く | エンジニアが作業を始められない | 各変数に単位とデフォルト値を付ける |
| 3つの層が混ざっている | 最初の段落からコードを出す | 意思決定者は離脱し、専門家はくどいと感じる | 層ごとに段落を分け、各層を独立させる |
技術記事のトーンも控えめに。 「革命的」「画期的」といった言葉は使わないでください。専門的な読者はマーケティング的な話し方に非常に敏感です。トーンの規範は次を参照してください。公式サイトのトーン規定動画の文字起こしを技術記事に直すときは特にここに注意する。話し言葉は書き言葉の判断文に変える。方法は次を参照動画文字起こしのコンテンツ化。
FAQ よくある質問
技術記事は読者を専門家と想定すべきか？
良い技術のたとえはどう選ぶ？
コード例はどれくらいの長さが適切？
技術記事の数式には既定値を付けるべき？
たとえは読者を誤解させる？
技術記事で E-E-A-T の信頼性はどう築く？
最後に
技術記事を書く核心は、複雑なことを簡単に話すことではなく、複雑なことを層に分けて正しく話すことだ。意思決定者にはたとえ、エンジニアには例、実装者にはパラメータ。3 つの層はそれぞれ独立し、互いに依存しない。読者は必要な層だけを持ち帰る。
導入は3ステップ。今週は既存の技術記事を1本選び、3層構造で書き出しを書き直す。来週はすべてのコード例を5分で動かせる形に整える。3週目はすべての計算式に既定値と単位を補う。この3ステップを終えれば、技術記事の読了率も問い合わせの質もはっきり改善する。
覚えておきたい一言。技術記事の信頼は「読者がすでに知っていることは説明しない」ことから生まれる。層を分けるのは手抜きではなく、3タイプの読者への敬意だ。