技術記事執筆 研修講座

この講座は、技術記事を書く・レビューするときに役立つ一般的な原則と方法論を、実務で使える形に整理した研修教材です。特定の書籍や記事を複製したものではなく、広く知られた考え方を独自に再構成しています。

ここで紹介する内容は「正解」ではなく「たたき台」です。読者層やテーマによって最適解は変わります。ご自身の状況に合わせて取捨選択していただければと思います。

4つの基本原則

どの章にも共通する土台として、次の4点を最優先で意識します。

執筆のフェーズ

執筆は次の流れで進めます。各フェーズのチェックリストは「14章」に集約しています。

テクニックの前に、書く目的と姿勢を整えておきます。ここがぶれると、技術が上がっても記事は刺さりません。

• 記事の目的は「読者への貢献」。自己成長・評価・収益は結果として後からついてくるもので、目的そのものに据えません。
• 対象読者は「少し前の自分」を基準にします。その時期の自分が読んで助かる粒度・前提で書きます。
• 完璧より継続。1本で完成形を目指さず、公開後も磨き続ける前提で書きます。
• 正確性は信頼の土台。曖昧なら断定せず、裏取りできた範囲で書きます(→ 8章)。
• 継続が最大の価値。単発の名作より、ゆるく長く出し続けることが資産になります(→ 13章)。

何を書くかは、書ききれるかどうかと、読まれるかどうかをほぼ決めます。採否の基準はシンプルです。

• 「少し前の自分が喜ぶか」で判断します。読んで助かる人が1人でも想像できれば、書く価値があります。
• 書きやすく価値が出やすい型を優先します。
  • トラブルシューティング(ハマった→原因→解決)
  • How-To(やりたいこと→実現手順)
  • 新機能・ツール紹介に自分の見解・優先順位を足したもの
  • やってみた / 体験談(失敗・工夫を含む)
  • 入門・学習法、書評、登壇 / 参加レポート
• 自分の体験・考察・主観を必ず混ぜます。事実の列挙だけなら生成AIで代替できます。人間が書く価値は「私がやった / 感じた」に宿ります。
• 既存記事の劣化コピーを作りません。日本語化・最新化・わかりやすさ向上・別観点など、新規価値を1つ以上足せるときだけ書きます。参考元は必ず明記します。
• ネタは鮮度が命です。「書きたい」と思った熱量が高いうちに着手します。寝かせるほど書かれなくなります。

正確さは信頼の前提です。調べ方が雑だと、どれだけ文章がうまくても記事の価値は下がります。

• 一次情報を当たります。公式ドキュメント・README・ソースコード・issue・PR を確認し、ネット記事や生成AIの出力を鵜呑みにしません。
• 参照した情報の投稿日・対象バージョンを確認し、古い情報に基づいていないかを点検します。
• 自分の言葉で説明できる状態まで理解します。丸写しは避け、「質問されたら答えられるか」を理解度の基準にします。
• 長い記事は先にアウトライン(見出しの親子関係)を組みます。発散しがちなら、一度トピックを俯瞰整理してから順序を決めます。
• 参考にした記事・書籍・公式ページは参考文献として控えておきます(記事末に列挙)。

はじめに・まとめ・タイトルの三位一体

• 「はじめに」で、何を扱うか / 読むと何が得られるか(読者メリット)/ 対象読者は誰か / 前提知識・実行環境を宣言します。読者が冒頭で「自分向けか」を判断できるようにします。
• 「まとめ」で要点を1〜2文で再提示します。尻切れを避け、読後感を整えます。
• タイトル・はじめに・まとめは同じテーマを指すようにします。3つがずれていたら、本文が脱線している兆候です。

見出し

• 使うのは h2 と h3 のみ。階層は h1 → h2 → h3 の順を崩さず、深くしすぎません。
• 見出しは読者にとっての視覚的な区切りであり、記事全体の地図です。本文を読まなくても構成が分かるようにします。
• 1画面に2〜3個見えるくらいの頻度(おおむね数百文字ごと)を目安にします。
• 見出しは短く(目安30字以内)・具体的に。問いや要点を込めると注意を引けます。

流れと密度

• 説明は段階的に並べます(「エラー→原因→解決」「やりたいこと→実現方法」など)。
• 結論までが長いときは、冒頭にTL;DR(要点3〜5項目)や結論を先置きします。
• 文章と図表・コードの分量はどちらかに偏らせません。文章だけ・コードだけのブロックが続かないよう、説明→コード→結果と交互に配置します。

• 本文を書き上げてから決めます(内容を要約する形が決めやすいため)。
• 抽象的なタイトル(「React基礎」)を避け、内容が想像できる具体性を持たせます(何が分かる / できるか)。
• 対象技術・対象読者・読者メリットを織り込みます。紛れやすい概念は 【React】 のように技術名を冠します。
• 重要語を先頭に置きます(一覧で末尾が「…」と省略されても意味が通るように)。
• 多少長くても、短く曖昧より明確を優先します。
• 煽り・釣り・内容が伴わないタイトルは避けます。タイトルで掲げた価値は、本文で必ず提供します。

• 文体を統一します(です・ます調で統一。途中で「〜しましょう」等を混ぜない)。
• 一文を短く。長い文は分割し、最も伝えたいことを先に置きます。
• 主語・述語を省略せず、対応を合わせます(「Aは〜される / する」の不一致を避ける)。
• 接続の「が」は逆接のときだけ。単純接続は「〜したところ」「〜した。その結果」等に言い換えます。
• 逆接(しかし / ですが / とはいえ)を連続させません。続くなら主張が定まっていない兆候です。
• 同じ文末(〜です / 〜ません)を連続させません。語尾に変化をつけます。
• 弱気表現を減らします(「〜かもしれません」「〜な気がします」を多用しない)。事実は言い切り、意見は押しつけない、を区別します。
• 多義的な言葉を避けます(「適当に」「いろいろ」等は具体語に置き換える)。
• 難しい漢字・補助動詞は開きます(例:「もちろん」「しばらく」「〜してみる」「〜してほしい」)。
• ブラウザ表示前提で1文ごとに改行します。読点での手動改行はしません(端末幅で崩れるため)。
• 推敲は読者モードに切り替えて複数回読み直します。一度寝かせてから読むと粗が見えます。

リライト例(Before / After)

上の原則を1文に当てはめると、読みやすさがどう変わるかの一例です(本講座オリジナルの作例)。

• 嘘をつきません。掲載前に実際に動かし、説明・実行結果と一致させます。編集フォームに直書きしません。
• 当たり前品質を満たします(正しいインデント=半角スペース、一貫した記法、言語標準の命名規則、全角混入なし、Lint通過)。
• コードブロックで掲載し、コピペ可能にします。画像にしません(コピー・検索ができなくなるため)。
• 言語指定を正確に。ログ・ターミナル出力・エラーなど整形不要なものには言語指定をしません。
• 実行結果を併記します(コンソール出力・画面表示・テスト結果など)。
• コピペで動く完全性を意識します。必要な import を含め、省く場合は「…略…」と明示します。
• 意味のある名前を使います(foo / bar / hoge は原則避ける)。
• 難易度は段階的に上げます。最小例から始め、要素を1〜2個ずつ追加します。
• 業務コードをそのまま貼りません。記事用に最小化・匿名化します。環境名・ファイル名も伏せます。
• セキュリティに配慮します。初心者がコピペしても危険でないコードにします。
• バージョン情報を明記します(言語・FW・ライブラリ・OS・DB など)。
• 例示用の値は予約ドメイン(example.com 等)を使います。

差分は diff 形式で見せる

Before / After を見せるときは diff が分かりやすく、コメントは行末でなく対象行の前の行に置くと横スクロールを避けられます。

# タイムアウトを延ばして再試行に対応
- client = Client(timeout=3)
+ client = Client(timeout=30, retries=3)
  response = client.fetch(url)

• テキストで伝わりにくい構造・概念は図解します。
• スクリーンショットは必要部分だけを、あらかじめ小さめのウィンドウで撮ります(スマホ表示でも読めるように)。注釈・強調を加えます。
• エラーや出力は画像化しません(テキストで載せる=検索・コピー可能)。
• 動き・操作フローは GIF / 動画で示します。
• 見出し・本文・コード・図のバランスを取り、単調さを避けます。
• アクセシビリティ:画像には内容を表す代替テキスト(alt)を付け、情報を色だけに依存させません(形・ラベル・凡例でも区別できるように)。

• 日付は年から書きます(「3月のアップデート」→「2026年3月のアップデート」、「現時点」→「2026年◯月時点」)。
• 技術名の表記を公式に合わせます(Java / GitHub / macOS / PostgreSQL など、大小・スペース)。
• 他者テキストの引用は > で明確に区別し、出典を示します。GitHubコードは可変な main ブランチではなく、commit SHA(または不変運用のタグ)+ 行番号の permalink で参照します。GitHub では対象行を選んで y キーで固定URLを取得でき、Markdown ファイルの行には ?plain=1#L14 のように ?plain=1 を付けます。
• おことわりを先回りで書きます(「初心者向けのため詳細は割愛」「特定環境での確認のみ」など)。
• オピニオン系は前提・背景・自分の立場を冒頭に書き、読者が文脈を共有できるようにします。
• 公開前に可能なら第三者(人 / AI / 公式)にファクトチェックを依頼します。
• ライセンスを守ります(出典表記・改変可否・商用可否を確認)。サンプルのリポジトリは特定 commit に固定します。
• 生成AIの出力を含める場合はその旨を明記し、内容は自分で検証してから載せます。事実・コードの正しさの責任は書き手にあります。

> 引用文はこのように示します。
> 複数行でも各行に > を置きます。

出典: 公式ドキュメント(2026年3月時点)

• 主語を小さくします。「エンジニアはみんな〜」ではなく「私は〜」。
• 価値観を押しつけません。「こうすべき」より「自分はこうした」。
• 他者・他技術を否定形で貶めません。「A は B より合う場面がある」と書き、「B はダメ」とは書きません。異論が出やすいテーマでは「異論は歓迎します」と前置きします。
• 愚痴・批判過多を避け、ウケ狙いのジョークに頼りません。
• 怒りで即公開しません。一晩寝かせて冷静に読み直します。

生成AIで下書きを作る人が増えました。だからこそ、AIに任せきりにしない工夫が差になります。

• 教科書的な要約だけにしません。予期せぬ失敗・発見・回り道といった「経験」こそ、人間の読者が価値を感じる部分です。実体験があるなら必ず織り込みます。
• 個性・クセ・ざらつきを残します。完璧に流暢で無個性な文章は「情報はあるが人がいない」読後感になり、印象に残りません。
• 表現の部分的なブラッシュアップに AI を使うのは有効です。ただし全体を機械任せにせず、構成・主張は自分で決めます。
• 4つの基本原則(深掘り / 断定しすぎない / 上から言わない / 環境名を伏せる)を最優先で守ります。

• 書き手モードから読者モードに切り替えて再読し、スマホでプレビューして崩れを確認します。
• タグ / トピックは最大5個。中心技術から優先します。方言のある技術は実行環境(MySQL / PostgreSQL 等)も併記し、表記は記事数の多い標準形に合わせます。新規タグの乱立は避けます。
• 関連する過去記事への「あわせて読みたい」導線を検討します。
• シェアは手動でひとこと添えて行います。「自分の記事であること」と「読者メリット」を明記します。
• 公開直後だけでなく時間を空けて複数回シェアします。社内 Slack や技術コミュニティにも共有します。
• 公開後も運用します。指摘は加筆修正で反映し、陳腐化したらアップデート(打ち消し線+追記+更新通知)します。

• 反応がない=劣っている、ではありません。露出機会やフォロワー数の問題です。継続で土台が育ちます。最初は反応が乏しくて当然で、数十本続けて時々「当たり」が出る程度に見積もります。
• バズは運の要素が大きいです(対象読者の母数に依存)。「付いたらラッキー」程度に構えます。
• バズは一過性です。数日で平常のアクセスに戻り、通りすがりの大半は固定読者になりません。次も気負わず平常運転で書き続けます。
• ネガティブコメントは読まれている証拠でもあります。客観視します。
• 技術的な指摘は、知識を分けてもらえる機会でもあります。納得できれば直して感謝します。返しにくい / 攻撃的なものはスルーしてかまいません。
• 無言のいいね・シェアも、立派なポジティブ反応として数えます。
• 承認欲求は燃料ですが、暴走させません。「バズるため」に内容が劣化していないか、時々自問します。

書く力よりも「出し続ける力」が、最終的な差になります。続けられる仕組みと心構えを持ちます。

動機と継続

• 自分が書く動機を一度言語化しておきます(「誰か1人は役に立つ」「自分用の記録」など何でも)。動機があると失速しにくくなります。
• 「読者にとっての価値(誰がどう嬉しいか)」を常に自問します。1つ言えれば書く価値があります。
• 反応・収益は「付いたらラッキー」程度に置きます。狙うのは評判・信用の蓄積で、それが後の登壇・寄稿・仕事の依頼につながります。
• 気楽に、細く長く。毎日更新のような高すぎるハードルを課しません。月1本、つらければさらにゆっくりでよいです。

時間とスピード

• 「書きたい」と思った瞬間が熱量の最高潮です。寝かせるほど熱は冷め、お蔵入りになります。思い立ったら早く着手します。
• 執筆に時間をかけすぎません。標準的な分量なら上限(目安2〜3時間)を決め、完璧を待たずに公開します。
• 完璧さより個性。流暢で無個性な文章より、書き手のクセ・経験というざらつきが残るほうが記憶に残ります。

公開先・運用の判断

• 公開先を使い分けます。技術が主役のネタは技術系プラットフォーム(Qiita / Zenn)、自分が主役の話や規約に馴染みにくい内容は個人ブログへ。各サービスのガイドライン適合で判断します。
• マルチポスト(同一記事の複数同時投稿)は基本的に避けます。修正の二重管理・反応の分散・どれが本家か不明、というデメリットが大きいためです。良い記事は1か所でも SNS 経由で届きます。
• アドベントカレンダー等の企画は、ネタ探し不要・締切効果・お祭り感で継続に効きます。ただし投稿が集中する時期は埋もれやすいので、力作は時期をずらす選択肢も持ちます。

認知とキャリア

• 名前・アイコンを複数プラットフォームで統一すると認知されやすく、思わぬ依頼の機会も逃しにくくなります。実名・顔出しは必須ではありませんが、認知と信用につながりやすいです。
• 他者の記事へのいいね・シェア・コメントも立派なアウトプットです。コミュニティ内の関係が育ち、巡り巡って自分の記事にも還ってきます。
• 記事を書く力は登壇・書籍・仕様書・チャット説明にそのまま応用できます。「相手に分かりやすく伝える」技術は職場評価にも直結します。

公開前に使える実践チェックリストです。チェックは自動保存され、次回も同じ状態で再開できます。

企画・調査

構成・タイトル

文章

コード・図表

正確性・配慮

公開・運用

記事の型を決めたら、対応する構成スケルトンを下敷きにします。あくまで一例で、内容に応じて見出しは自由に足し引きします。どの型でも共通して、長くなる節には見出しを足し、「見出しを追うだけで概要が掴める」状態を保ちます。

本講座では、これらの型を「目的タイプ(A〜F)」でグルーピングしています。型は厳密な分類ではなく、1本の記事が複数の型をまたぐこともあります。迷ったら「読者が何を得たいか」から逆算して型を選んでみてください。

記法の「入力」と「表示結果」を並べて確認できます。タブを切り替えると、ソースとプレビューを行き来できます。特記なき記法は Qiita・Zenn 両対応です。

強調・装飾

**太字** または __太字__
~~打ち消し線~~

斜体(*…*)は日本語では
見栄えしないため基本使いません。

テーブル

| 項目 | 値 |
|:-----|---:|
| 左寄せ | 右寄せ |
| name | 100 |

リスト

- 親項目
  - 子項目(スペースでインデント)

1. 一つ目
1. 二つ目
1. 三つ目

引用

> 行頭に > を置きます。
> 連続行でも毎行 > を置くのが安全です。
>
> - 引用内でも箇条書きが使えます

注意・警告ボックス(方言)

:::note info
補足(緑)
:::

:::note warn
注意(黄)
:::

:::note alert
警告(赤)
:::

コードブロック(言語・ファイル名指定)

```tsx:Button.tsx
export const Button = () => {
  return <button>OK</button>;
};
```

export const Button = () => {
  return <button>OK</button>;
};

差分(diff)付きコードブロック

```diff_js
- const a = 1;
+ const a = 2;
```

Qiitaは diff_js(_区切り)
Zennは diff js(スペース区切り)

- const a = 1;+ const a = 2;

うっかりメンション対策(重要)

脚注

本文に脚注をつけます[^1]。

[^1]: これが脚注の内容です。

ラベルは任意で、番号は自動です。Zenn はインライン脚注 本文^[注釈] も使えます。

エスケープ・HTML・埋め込み

• 記号が Markdown と誤認される場合は、直前に \ を置いてエスケープします(例: 顔文字)。
• HTMLタグの直書きは、Qiita は多くのタグに対応します。Zenn は <br> と HTML コメントのみです。
• 埋め込みは、Qiita が Speaker Deck 等の <script> タグ、Zenn は @[speakerdeck](スライドID) 形式です。