blog-writing-guide

Sentry 博客写作技能

这项技能确保每篇博客都符合 Sentry 的写作标准——无论你是在帮助工程师写第一篇博客，还是在协助营销人员撰写产品公告。

标准： 每篇 Sentry 博客都应该值得资深工程师分享到团队的 Slack，或在技术决策时作为参考。

接下来是需要内化并应用于每篇内容的核心原则。

Sentry 的语气

我们的风格： 像一位资深开发者在会议后的派对上，兴致勃勃地讲解某件事——聪明、具体、略带不羁，而且知识渊博。

我们不会这样写： 企业博客、新闻稿、销售演示文稿或 AI 生成的摘要。

表达要技术准确、有主见、直截了当。欢迎幽默，但幽默应为内容服务，而不是取而代之。可以讽刺，但每篇博客有一个好笑话就够了。

使用“我们”（Sentry）和“你”（读者）。这是对话，不是论文。

禁用措辞

绝不要使用以下措辞。它们会自动亮起红灯：

• “我们很高兴／激动地宣布”——直接宣布即可
• “同类最佳”／“行业领先”／“尖端”——用事实证明，不要空口声称
• “无缝”／“无缝地”——没有什么是真正无缝的
• “赋能”／“借助”／“释放”——说清楚你真正想表达的意思
• “强大”——具体描述它强大在哪里
• “在 [Company]，我们相信……”——直接说出这个观点
• “简化流程”——人人都在简化流程，别再说了
• 填充式过渡语：“话虽如此，” “值得注意的是，” “归根结底，” “闲话少说，” “你可能知道”
• “在这篇博客中，我们将探讨……”——开门见山，直接开始

开篇（前 2–3 句话）

开篇必须做到以下两点之一：提出问题或陈述结论。绝不要从背景、公司历史或炒作开始。

好的示例：“上线前两周，我们砍掉了整个指标产品。下面解释为什么预聚合时序指标无法满足调试需求，以及我们如何从头重建了系统。”

不好的示例：“在 Sentry，我们始终在寻找改善开发者体验的方法。今天，我们很高兴与大家分享指标产品的一些激动人心的更新，相信你一定会喜欢。”

结构：围绕读者的问题展开

每篇博客都应围绕读者真正想知道的问题来组织，而不是围绕你的内部叙事：

1. 这解决了什么问题？（最多 1–2 段）
2. **它实际上是如何工作的？**重点讲底层技术，而不是你要点击哪些按钮。（这是文章主体——要具体）
3. 有哪些权衡或替代方案？（这能区分优秀与卓越）
4. 我该如何使用／试用／实现它？（给出具体的后续步骤）

对于工程技术深度文章，还要回答： 5. 我们尝试过哪些行不通的方法？（建立信任） 6. 有哪些已知限制？（体现求真务实）

便于快速浏览的排版

人们会快速浏览内容。段落越短，越能让读者继续读下去。

在对比处另起一段。 当句子引出“但是”“然而”或转换视角时，就另起一段。不要把转折埋在大段文字里。

不佳：

传统监控会跟踪请求和延迟。这适用于无状态 HTTP 服务。AI Agent 则有所不同。一次运行可能涉及多次大模型调用、工具执行和交接。

较好：

传统监控会跟踪请求和延迟。这适用于无状态 HTTP 服务。

AI Agent 则有所不同。一次运行可能涉及多次大模型调用、工具执行和交接。

在对比点之前换行，能形成视觉强调。尽管这不符合传统的段落规则，却是在线写作的常见做法。

每段只表达一个观点。 如果一段涵盖两个不同的要点，就拆成两段。三句一段没有问题。为了强调，单句成段也没有问题。

不要使用长破折号。 改用逗号、句号或换行。长破折号在印刷品中没有问题，但会让博客排版显得杂乱。

面向开发者内容的 SEO

针对竞争激烈的搜索查询时：

先讲通用内容，最后落到具体内容。 帖子前 50%-60% 应介绍与工具无关的知识性内容（定义、概念、指标、最佳实践）。在后半部分再将你的产品作为实现示例引入。对于信息类查询，Google 给指南的排名通常高于产品页。

在 H2 标题中加入关键词。 通用标题不利于搜索。“AI Agent 监控的关键指标”比“要衡量什么”更好。（优质和不佳的示例请参阅下文的章节标题。）

加入定义性章节。 对于任何核心术语（如“Agent 可观测性”“错误监控”），排名靠前的页面几乎总会有一个“什么是 X？”章节。即使觉得内容基础，也要加入这一章节。

添加常见问题。 在文章末尾加入 3-4 个针对长尾关键词的问题。这有助于获得精选摘要和“用户还会问”搜索结果框。

应避免的 AI 写作模式

大模型生成的文字往往会露出一些痕迹。请标记并改写以下内容：

戏剧化的短句。

• 不佳：“没有错误。没有警告。一切正常。”
• 较好：“没有错误或警告，一切看起来都很正常。”

像保险杠贴纸一样的格言。

• 不佳：“看不见的东西，就无法修复。”
• 较好：“如果看不到完整的请求生命周期，你就只能靠猜。”

三段式揭示。

• 不佳：“不是配置问题。不是代码错误。部署版本过时了。”
• 较好：“这不是配置问题，也不是代码错误，而是部署版本过时了。”

故作高深地简化。

• 不佳：[代码块]“就这样。这就是你需要的全部。”
• 较好：[代码块] 然后解释这段代码的作用，或者直接继续后文。

广告文案式的平行结构。

• 不佳：“指标告诉你哪里出问题了。追踪告诉你为什么。”
• 较好：“指标能显示哪里出了问题，但你真正弄清原因的地方是追踪。”

只在开头和结尾体现个性。 AI 草稿会以个人轶事开头，在 80% 的正文中语气变得不带个人色彩，最后以行动号召收尾。作者的个人风格应贯穿全文。

• 不佳：个人化开场 → 客观冷静的正文 →“免费试用 Sentry。”
• 较好：在正文中穿插第一人称的补充：“这部分让我一开始很困惑”／“我本来会怪错服务。”

章节标题必须传达信息

较弱：“背景”“架构”“结果”“结论”

较强：“为什么时间序列预聚合会破坏调试上下文”“分布式 GROUP BY 的分散-收集方法”“这种方法的局限：基数墙”

技术质量标准

用数字代替形容词。 如果你声称性能有所提升，请给出具体数字。

• 不佳：“这显著缩短了错误处理时间。”
• 较佳：“这将错误处理的 p99 耗时从 340ms 降至 45ms，提升了 7.5 倍。”

代码必须可运行。 如果文章包含代码，请先进行测试。提供导入语句、配置和上下文。注释应解释原因，而不是内容。

系统要配图。 如果你描述的系统包含两个以上相互作用的组件，请附上图示。使用真实的服务名称标注，而非通用方框。

诚实胜过炒作。 切勿夸大功能的作用。承认其局限性。如果功能处于 beta 阶段，请明确说明。如果竞争对手在某些方面做得不错，可以如实指出。不要声称 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 句话内吸引读者
• 通过“我会分享这篇内容吗？”的检验
• 没有官样文章、填充内容或空话
• 标题能传达信息
• 篇幅恰当（不拖沓，也不过于简略）
• 标题具体且引人注目

最终检查：

• 作者署名正确（真实姓名）
• 包含文档／入门指南链接
• 文章没有重复变更日志中的内容

提供反馈时，要具体且有建设性。引用薄弱的段落，说明问题所在，并通过改写展示应有的水准。