blog-writing-guide

Sentry ブログ執筆スキル

このスキルは、エンジニアが初めてブログ記事を書くときも、マーケターが製品発表の下書きを作成するときも、すべての記事で Sentry のブログ執筆基準を徹底します。

基準： Sentry のブログ記事はどれも、シニアエンジニアがチームの Slack で共有したり、技術的な判断の参考にしたりするような内容であるべきです。

以下に、すべてのコンテンツで身につけ、実践すべき基本原則を示します。

Sentry の語り口

目指す語り口： カンファレンスの打ち上げで、本当に夢中になっていることを説明するシニアデベロッパーのように。頭の回転が速く、具体的で、少しくだけていて、深い知識がある語り口です。

避ける語り口： 企業ブログ、プレスリリース、セールス資料、AI が生成した要約のような語り口です。

技術的に正確で、明確な意見を持ち、率直に書きます。ユーモアは歓迎しますが、内容を引き立てるものであるべきで、内容に取って代わるものであってはいけません。皮肉も効果的です。記事ごとに、気の利いたジョークがひとつあれば十分です。

「we」（Sentry）と「you」（読者）を使います。論文ではなく、会話です。

禁止表現

次の表現は絶対に使わないでください。使うと、即座に警戒されます。

• 「We're excited/thrilled to announce」――そのまま発表しましょう
• 「Best-in-class」／「industry-leading」／「cutting-edge」――言葉で主張せず、実例で示しましょう
• 「Seamless」／「seamlessly」――シームレスなものなどありません
• 「Empower」／「leverage」／「unlock」――本当に伝えたいことを表現しましょう
• 「Robust」――何が堅牢なのかを説明しましょう
• 「At [Company], we believe...」――信念をそのまま述べましょう
• 「Streamline」――誰もが効率化を掲げています。もうやめましょう
• 内容のないつなぎ表現：「That being said,」「It's worth noting that,」「At the end of the day,」「Without further ado,」「As you might know」
• 「In this blog post, we will explore...」――率直に、本題から始めましょう

冒頭（最初の2～3文）

冒頭では、問題を提示するか、結論を述べるかのどちらかを必ず行います。背景、会社の歴史、誇張から始めてはいけません。

良い例：「ローンチの2週間前、私たちはメトリクス製品全体を廃止しました。時系列メトリクスの事前集計がデバッグで機能しなくなる理由と、システムをゼロから再構築した方法を紹介します。」

悪い例：「Sentry では、開発者体験を改善する方法を常に探しています。本日、きっと気に入っていただけるメトリクス製品のエキサイティングな最新情報をお知らせできることを嬉しく思います。」

構成：読者の疑問に沿う

記事の構成は、社内のストーリーではなく、読者が実際に知りたいことを中心に組み立てます。

1. どんな問題を解決するのか？（最大1～2段落）
2. 実際にはどのように動くのか？ ボタンの操作方法ではなく、基盤となるテクノロジーを説明します。（記事の大部分を使い、具体的に説明します）
3. どのようなトレードオフや代替案があったのか？（良い記事と優れた記事を分ける要素です）
4. どう使う／試す／実装するのか？（具体的な次のステップ）

エンジニアリングの技術解説記事では、次の点にも触れます。

5. 試したけれどうまくいかなかったことは何か？（信頼につながります）
6. 既知の制限事項は何か？（知的誠実さを示します）

読みやすさを高める書式設定

人はスクロールしながら読みます。読者に読み続けてもらうには、段落は短いほうがほとんどの場合効果的です。

対比する箇所で段落を分けます。 文の中で「しかし」や「ところが」が出てくる場合や、視点が切り替わる場合は、新しい段落を始めます。文章の塊の中に転換点を埋もれさせないでください。

悪い例：

従来のモニタリングでは、リクエストとレイテンシーを追跡します。ステートレスな HTTP サービスではこれでうまくいきます。AI エージェントは異なります。1 回の実行で、複数の LLM 呼び出し、ツールの実行、引き継ぎが発生することがあります。

良い例：

従来のモニタリングでは、リクエストとレイテンシーを追跡します。ステートレスな HTTP サービスではこれでうまくいきます。

AI エージェントは異なります。1 回の実行で、複数の LLM 呼び出し、ツールの実行、引き継ぎが発生することがあります。

対比する箇所の前で改行すると、視覚的に強調されます。従来の段落のルールには反しますが、オンライン記事では一般的な書き方です。

1 段落につき 1 つの考えを述べます。 段落で異なる 2 つの要点を扱う場合は、分けてください。3 文の段落でも問題ありません。強調するためなら、1 文だけの段落でも構いません。

ダッシュ記号は使いません。 代わりに、コンマ、ピリオド、改行を使います。ダッシュ記号は印刷物では問題ありませんが、ブログの書式では視覚的なノイズになります。

開発者向けコンテンツの SEO

競争の激しい検索クエリを狙う場合：

一般的な内容から始め、具体的な内容で締めくくります。 記事の最初の 50〜60% は、ツールに依存しない教育的なコンテンツ（定義、概念、指標、ベストプラクティス）にします。後半で、実装例として自社製品を紹介します。Google は情報を探す検索クエリに対し、製品ページよりガイド記事を上位に表示します。

H2 にキーワードを入れます。 一般的な見出しでは検索に表示されません。「測定する項目」よりも「AI エージェントのモニタリングに重要な指標」のほうが効果的です。（良い例と悪い例については、以下の セクション見出し を参照してください。）

定義を説明するセクションを入れます。 主要な用語（「エージェントの可観測性」「エラー監視」など）について、検索結果の上位ページにはほぼ必ず「X とは？」というセクションがあります。基本的すぎるように感じても、入れてください。

FAQ を追加します。 記事の最後に、ロングテールキーワードを狙った質問を 3〜4 個入れます。強調スニペットや「他の人はこちらも質問」ボックスに表示される可能性があります。

AI が書きがちな表現を避ける

LLM 生成の文章には、特徴的なパターンがあります。見つけたら、指摘して書き直してください。

劇的な断片を並べる表現。

• 悪い例：「エラーなし。警告なし。すべて正常。」
• 良い例：「エラーも警告もなく、すべて問題ないように見えました。」

標語のような格言。

• 悪い例：「見えないものは直せません。」
• 良い例：「リクエストのライフサイクル全体を把握できなければ、推測するしかありません。」

3 段階で明かす表現。

• 悪い例：「設定の問題ではない。コードのバグでもない。デプロイが古かった。」
• 良い例：「設定の問題でもコードのバグでもありませんでした。デプロイが古かったのです。」

分かったような単純化。

• 悪い例：[コードブロック]「以上です。必要なのはこれだけです。」
• 良い例：[コードブロック]の後にコードの動作を説明するか、そのまま次に進みます。

並列構造の広告文。

• 悪い例：「メトリクスから問題が分かります。トレースから原因が分かります。」
• 良い例：「メトリクスで問題を確認できますが、実際に原因を突き止めるにはトレースが役立ちます。」

冒頭と締めくくりにしか個性がない文章。 AI の下書きは、個人的なエピソードで始まり、記事の 80% は無機質な文章が続き、最後に行動喚起で締めくくられがちです。著者の語り口は記事全体を通して保ってください。

• 悪い例：個人的な導入 → 無機質な中盤 → 「Sentry を無料でお試しください。」
• 良い例：「ここでつまずきました」「別のサービスのせいだと誤解していたと思います」といった個人的なコメントを、記事全体に織り交ぜます。

セクション見出しは情報を伝える必要があります

弱い例： 「背景」「アーキテクチャ」「結果」「結論」

強い例： 「時系列データの事前集計がデバッグのコンテキストを損なう理由」「分散 GROUP BY に対する scatter-gather アプローチ」「この手法が行き詰まるところ：カーディナリティの壁」

技術品質基準

形容詞より数値を示してください。 パフォーマンスについて述べる場合は、数値を含めてください。

• 悪い例：「エラー処理時間を大幅に短縮しました。」
• 良い例：「エラー処理の p99 を 340ms から 45ms に短縮しました。7.5 倍の改善です。」

コードは動作する必要があります。 投稿にコードを含める場合は、テストしてください。インポート、設定、コンテキストも含めてください。コメントでは「何をするか」ではなく、「なぜそうするか」を説明してください。

システムには図を添えてください。 相互に連携するコンポーネントが 2 つを超えるシステムについて説明する場合は、図を含めてください。汎用的なボックスではなく、実際のサービス名をラベルにしてください。

誇張より正直さを優先してください。 機能の効果を誇張してはいけません。制限がある場合は認めてください。ベータ版であれば、その旨を明記してください。競合製品が優れている点に触れてもかまいません。AI 機能の能力を実際以上に主張してはいけません。「Seer が根本原因の候補を提示する」ことは、「Seer が根本原因を見つける」こととは異なります。

タイトルのガイドライン

タイトルは、投稿の中で最も効果の大きい一文です。RSS フィードや Twitter をスクロールしている開発者の目を引く必要があります。

強いタイトルは、具体的な主張をしたり、ストーリーを伝えたり、具体的な成果を約束したりします。

• 「私たちが作ったメトリクス製品はうまくいきました。それでも廃止して、ゼロから作り直しました」
• 「Salt を修正してリリースの遅延を 5% 削減した方法」
• 「JavaScript バンドルの 47% は使われていないコードです。見つけ方を紹介します。」

弱いタイトルは、曖昧な告知です。

• 「新しいメトリクス製品のご紹介」
• 「Sentry のパフォーマンス改善」
• 「Seer による AI デバッグ」

締めくくり

役立つ情報で締めくくってください。ドキュメントやソースコードへのリンク、試す方法、フィードバックの呼びかけなどを含めます。ありきたりな誇張表現（「皆さんが何を作るのか、楽しみにしています！」）、直前に述べた内容の要約、製品ページへの誘導（「Sentry を無料でお試しください。すべてのプランに含まれています。」）で終わらせてはいけません。冒頭のストーリーにつなげるか、読者が次にできる具体的なことを示してください。

投稿の種類

投稿の種類ごとの簡単な一覧です。

種類	目的	執筆者
エンジニアリングの詳細解説	技術システムや意思決定を説明し、ほかのエンジニアの学びにつなげる	実装したエンジニア。必ず本人が執筆します。
製品のローンチ	リリースしたもの、その重要性、使い方を説明する	PM、エンジニア、または DevEx。マーケティング担当者が開発したものでない限り、PMM は執筆しません。
ポストモーテム	タイムラインと修正内容を含む、透明性の高い障害分析	エンジニアリング部門のリーダー
データ／調査	Sentry 独自のデータ上の立場を生かした、独自の知見を紹介する	データチーム、エンジニアリング部門、またはリサーチチーム
チュートリアル／ガイド	開発者が具体的な作業を達成できるよう支援する	DevEx、エンジニア、またはコミュニティの貢献者

「これをシェアしたいか？」テスト

公開する前に、次のことを考えてください。開発者はこの投稿をシェアしたいと思うでしょうか？Hacker News に掲載される見込みはあるでしょうか？答えが「いいえ」であれば、投稿にはさらに深い内容や独自の知見が必要です。そうでなければ、変更履歴に載せるべきです。

シェアする価値のある投稿には、少なくとも次のいずれかが含まれています。

• トレードオフを踏まえて説明された技術的な意思決定
• ほかでは見つからない独自のデータや調査
• 具体的な詳細を含む、実際のデバッグ事例
• うまくいかなかったことについての正直な検証
• 読者の時間を実際に節約できるハウツー

絶対に守るべきこと（早見表）

1. 実在する人物の名前を記載せずに公開してはいけません。「The Sentry Team」のような執筆者表記は使わないでください。
2. 動作しないコードを公開してはいけません。
3. 「発表できることを嬉しく思います」とは書かないでください。発表するだけでかまいません。
4. システムを説明する場合は、図を含めてください。
5. パフォーマンスについて述べる場合は、数値を含めてください。
6. 意思決定について説明する場合は、選ばなかった案とその理由も説明してください。
7. 執筆を始める前に、すべての投稿について「誰に向けたものか」を明確にしてください。
8. 変更履歴は変更履歴に載せてください。ブログ投稿には、それ以上の価値を持たせてください。
9. 迷ったときは、さらに深く掘り下げてください。浅すぎる内容になるリスクは、詳しすぎる内容になるリスクをはるかに上回ります。
10. 自分がこの問題を解決しようとしていたときに存在してほしかった投稿を書いてください。

ドラフトのレビューまたは編集を行う際

次の両方のチェックリストに沿って確認してください。

技術レビュー：

• 技術的な主張がすべて正確である
• コードサンプルが動作する
• アーキテクチャの説明が実態と一致している
• 数値やベンチマークが正しい
• 専門家が見て呆れるような過度な単純化がない

編集レビュー：

• 冒頭の2文以内で読者の興味を引いている
• 「これは誰かに共有したいか？」という基準を満たしている
• 企業的な言い回し、埋め草、冗長な表現がない
• 見出しから内容が伝わる
• 適切な長さである（冗長でも簡潔すぎでもない）
• タイトルが具体的で魅力的である

最終確認：

• 著者名の表記が正しい（実在する人物の名前）
• ドキュメントや導入ガイドへのリンクが含まれている
• 投稿が変更履歴の内容と重複していない

フィードバックを提供する際は、具体的かつ建設的にしてください。問題のある箇所を引用し、なぜ問題なのかを説明したうえで、求める水準を示す書き換え例を提示してください。