Blog Writing Guide Ja

日本語技術ブログ執筆ガイド

日本語の技術ブログ記事に品質基準を課すスキル。 対象は個人ブログ、Zenn、Qiita、企業テックブログの記事全体である。 記事の企画、構成、新規執筆、記事全体のレビュー、大規模なリライト、タイトルと見出しの検討に使用する。

原則として、Aboutページ、README、AGENTS.md、スキル定義、SNS投稿、メール、短い説明文、front matterだけの編集、タグ整理、コードコメント、記事内の一文や一段落だけの軽微な推敲には使用しない。 対象外の文章でも日本語の文レベルの改善が必要なら、利用できる環境で writing-ja を使用できる。

このスキルは記事の企画、構成、タイトル、見出し、導入、結論、SEO判断、記事単位の品質バーとレビューを担当する。 writing-ja がある環境では、文レベルの推敲（事実関係、論理、具体性、文体の調整）をそちらに任せる。ない環境では、この記事単位の基準を使って文レベルも確認する。どちらの場合も、その段階をスキップしない。

品質基準

シニアエンジニアがチームの Slack に貼りたくなる記事を目指す。はてなブックマークや Zenn のトレンドに載る可能性が少しでもある記事。この基準に届かないなら、深さか独自の知見が足りていない。

その問題を解こうとしていた過去の自分が読みたかった記事を書く。迷ったら深くする。浅すぎるリスクは、詳しすぎるリスクよりはるかに大きい。

声

カンファレンスの懇親会で、本当に面白いと思ったことを語っているエンジニアの声で書く。 技術的に正確で、意見があり、率直。

プレスリリース、営業資料、AI生成の要約の声にしない。 ユーモアは内容に奉仕するときだけ入れる。1記事に1つで十分。

記事全体で避ける構成

見つけたら書き直す。文レベルの定型表現や語彙の候補は、利用できる環境では writing-ja の検査に任せる。

• 主張の代わりに、発表する喜びや抽象的な優位性だけを置く
• 導入が、読者の判断材料にならない予告だけで終わる
• 埋め草の前置きで、読者の判断に関係しない文章を増やす

書き出し（最初の2〜3文）

書き出しは「問題を述べる」か「結論を述べる」のどちらかにする。 背景説明、一般論、盛り上げから始めない。「近年、〜が注目されています」は禁止。

■良い例

リリース2週間前に、作っていたメトリクス製品を丸ごと捨てた。
時系列の事前集計がデバッグでは役に立たない理由と、ゼロから作り直した話を書く。

■悪い例

技術の変化を簡単に整理してから、本題を紹介します。
この製品に追加した機能をまとめます。

「この記事で分かること」

内容のない予告文は使わない。

記事で扱う具体的な範囲や、読者が得られる判断材料を示す短い「この記事で分かること」は使用してよい。 長く複数の論点を扱う記事で、導入文だけでは対象範囲が分かりにくいときに使う。

短い記事や導入文だけで対象範囲が明確な記事には機械的に追加しない。 本文や見出しを言い換えただけの抽象的な箇条書きにもしてはならない。

構成は読者の疑問に沿わせる

書き始める前に、誰に向けた記事かを決める。そのうえで、自分の社内事情や時系列ではなく、読者が実際に抱く疑問の順に組む。

1. これは何の問題を解決するのか（1〜2段落まで）
2. どういう仕組みで動くのか。操作手順ではなく、裏側の技術（記事の本体。具体的に書く）
3. 何と比較して、何を捨てたのか（良い記事と優れた記事を分けるのはここ）
4. どう使い始めるか（具体的な次の一歩）

技術深掘り記事ではさらに次を扱う。

5. 試してうまくいかなかったこと（信頼につながる）
6. 既知の制約（知的な誠実さを示す）

節ごとの厚みは、書き始める前に割り振る。全部の節を同じ熱量で書くと、よくできてはいるが誰の実感もこもっていない記事になる。一番言いたい主張と、自分が実際に迷った箇所や失敗した箇所を厚く書き、前提として片付けてよい話は1文で終わらせる。構成案の段階で全部の節が同格に見えるなら、そこが直す地点になる。

時系列と演出を混ぜない

障害調査やデバッグ記録では、発生順が因果の理解を助けるので時系列を残してよい。 ただし、書き手の発見順を読者に追わせることと、「思い込み→異変→種明かし→回収」を演出することは別物である。

読者が結果や再現手順を求める記事では、主要な結果を先に示し、時系列はその根拠として使う。 先のほのめかし、伏線、種明かし、冒頭の回収は、読者が因果を理解するために要る場合だけ残す。同じ役割の演出が記事に複数あるなら、一つに絞る。

流し読みへの対応

読者はスクロールする。段落は短いほうがほぼ常に読み続けてもらえる。

逆接や視点の転換（「しかし」「ただし」「ところが」）が来たら、その直前で段落を分ける。 転換点を段落の中に埋めない。

■悪い例

従来の監視はリクエストとレイテンシを追う。ステートレスな HTTP サービスならそれで足りる。AIエージェントは違う。1回の実行に複数の LLM 呼び出し、ツール実行、ハンドオフが含まれる。

■良い例

従来の監視はリクエストとレイテンシを追う。
ステートレスな HTTP サービスならそれで足りる。

AIエージェントは違う。
1回の実行に複数の LLM 呼び出し、ツール実行、ハンドオフが含まれる。

空行による転換の強調は、伝統的な段落規則からは外れるが、オンラインの文章では標準的な手法。

1段落には1つのトピックだけ置く。2つの論点を含む段落は割る。 強調のための1文段落も使ってよい。 箇条書きは、項目の並列や比較を示すほうが本文より読みやすいときに使う。網羅性や項目数をそろえるためだけに増やさない。

日本語ブログのSEO

検索流入を明確に狙う記事に適用する。

• 検索者が最初に必要とする結論、判断材料、解決策を前半に置く。
• 用語の定義が検索意図に含まれる場合だけ「〜とは」の説明を置く。
• 一般論は、読者が実装や判断を理解するために必要な範囲に限定する。
• FAQは、本文へ自然に組み込めない関連質問が複数ある場合だけ追加する。
• 定義節やFAQをSEO目的だけで機械的に追加しない。
• 不具合解決、設定手順、移行記録、体験記では、具体的な結果や手順を優先する。
• 検索キーワードのために不自然な反復や言い換えを増やさない。

実際に試した結果、失敗した方法、妥協点、不満点、選択理由、自分の環境でどうだったかを、一般論で薄めない。

書き手の声を記事全体に通す

AI の下書きは、個人的な導入で始まり、本文の80%が無人格になり、CTA で締まる。 書き手の声は全体を通して残す。「ここで自分はハマった」「最初は別のサービスを疑っていた」のような一人称の合いの手を本文に散らす。

文単位で出る LLM の癖（体言止めの三連打、標語化、対句、コードブロック直後の一言締め）は writing-ja の担当。

見出しは情報を運ぶ

• 弱い見出し「背景」「アーキテクチャ」「結果」「まとめ」
• 強い見出し「時系列の事前集計がデバッグ文脈を壊す理由」「分散 GROUP BY を scatter-gather で解く」「破綻するのはここ。カーディナリティの壁」

見出しだけ拾い読みしても記事の主張が追えるようにする。

技術的な品質基準

• 形容詞より数字。性能を主張するなら数字を入れる。「エラー処理が大幅に高速化した」ではなく「p99 のエラー処理時間が 340ms から 45ms になった。7.5倍の改善」
• コードは動くものだけ載せる。import、設定、前提を含める。コメントは what ではなく why を書く
• 3つ以上のコンポーネントが絡むシステムを説明するなら図を入れる。Mermaid でよい。汎用の箱ではなく実際のサービス名でラベルを付ける(作図と alt テキストの規約は blog-ops の references/images.md)
• 誇張しない。機能ができないことをできるかのように書かない。ベータならベータと書く。競合の優れた点に触れてよい。「AI が根本原因を提案する」と「AI が根本原因を特定する」は別物

一般論になっていないか検査する

段落から固有名詞、数値、実例をすべて抜いても文意が変わらないなら、その段落は一般論で止まっている。誰が書いても同じ内容になる段落は、言い回しを直しても中身が変わらない。

これは書き方ではなく素材の問題なので、文章を直すループを回し続けても解決しない。手を止めて、その段落を支える固有名詞、数値、一次情報、実際にやったことを集め直してから書き直す。素材を持っているのは書き手なので、手元になければ尋ねる。もっともらしい説明で埋めない。集まらないなら、その論点を記事から落とすか、一般論だと断ったうえで短く済ませる。

タイトル

タイトルは記事の中でもっともレバレッジの高い一文。 RSS や SNS のタイムラインをスクロールしている開発者の手を止められるかで判断する。

強いタイトルは、具体的な主張をするか、物語を予告するか、具体的な見返りを約束する。

• 「作ったメトリクス製品は動いていた。それでも捨てて作り直した」
• 「Salt を直したらリリース遅延が5%減った話」
• 「あなたの JavaScript バンドルの47%はデッドコード。見つけ方を書く」

弱いタイトルは漠然とした告知。

• 「新しいメトリクス製品のご紹介」
• 「パフォーマンス改善のお知らせ」
• 「AI を活用したデバッグ」

結び

役に立つもので終える。ドキュメントへのリンク、ソースコード、試す手段、フィードバックの窓口。 冒頭で始めた話に戻って回収するか、読者が次にやる具体的なことを示す。

汎用の盛り上げ（「今後の展開にご期待ください」）、直前に書いたことの要約、製品ページ調の CTA（「無料でお試しいただけます」）で終えない。

記事タイプ

いずれのタイプでも、書いた本人の体験と判断が入っていること。 機能一覧の紹介は changelog やリリースノートに書けばよく、ブログ記事にはそれ以上のものを載せる。

長さの目安

字数は目標ではなく、逸脱に気づくための物差しとして使う。範囲を外れること自体は問題ではないが、外れた理由を説明できるかは確かめる。

下限を大きく下回るなら、「何と比較して何を捨てたか」と「うまくいかなかったこと」が抜けている場合が多い。ここは深さを足す。 上限を大きく超えるなら、前提の説明が長いか、記事を分けるべき論点が同居している。読者の疑問の順に並べ直すと、どこが本題でないかが見える。

「共有されるか」テスト

公開前に問う。この記事を開発者が誰かに共有するか。はてなブックマークで伸びる見込みが少しでもあるか。 答えが No なら、深さか独自の知見を足すか、changelog 行きにする。

共有される記事は、少なくとも1つを含む。

• トレードオフ込みで説明された技術的な決定
• 他では読めない独自のデータや検証結果
• 具体的なディテールのある実録デバッグ物語
• うまくいかなかったことの正直な報告
• 読者の時間を実際に節約する手順

下書きをレビュー・編集するとき

references/review.md を読んでから始める。読む順序、3つのチェックリスト、指摘の返し方とレビューの完了条件がそこにある。