blog-writing-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sentry Blog Writing Skill

Sentry博客写作技能

This skill enforces Sentry's blog writing standards across every post — whether you're helping an engineer write their first blog post or a marketer draft a product announcement.

The bar: Every Sentry blog post should be something a senior engineer would share in their team's Slack, or reference in a technical decision.

What follows are the core principles to internalize and apply to every piece of content.

本技能用于统一所有Sentry博文的写作标准——不管你是协助工程师写他们的第一篇博客，还是帮营销人员起草产品公告都适用。

质量门槛： 每一篇Sentry博文都应该达到资深工程师愿意在团队Slack中分享，或是在技术决策中引用的水平。

以下是所有内容都需要内化并遵循的核心原则。

The Sentry Voice

Sentry语气规范

We sound like: A senior developer at a conference afterparty explaining something they're genuinely excited about — smart, specific, a little irreverent, deeply knowledgeable.

We don't sound like: A corporate blog, a press release, a sales deck, or an AI-generated summary.

Be technically precise, opinionated, and direct. Humor is welcome but should serve the content, not replace it. Sarcasm works. One good joke per post is plenty.

Use "we" (Sentry) and "you" (the reader). This is a conversation, not a paper.

我们应该像： 开发者大会afterparty上的资深工程师，在分享自己真心热爱的内容——聪慧、具体、带点不羁，又专业深厚。

我们不应该像： 企业官博通稿、新闻稿、销售PPT、AI生成的摘要。

要做到技术精准、观点明确、表达直接。可以加幽默内容，但要为内容服务，不能喧宾夺主，讽刺也可以使用，一篇博文有一个好的笑点就足够了。

使用「我们」（指代Sentry）和「你」（指代读者）的称呼，这是对话，不是学术论文。

Banned Language

禁用语言

Never use these. They are automatic red flags:

"We're excited/thrilled to announce" — just announce it
"Best-in-class" / "industry-leading" / "cutting-edge" — show, don't tell
"Seamless" / "seamlessly" — nothing is seamless
"Empower" / "leverage" / "unlock" — say what you actually mean
"Robust" — describe what makes it robust instead
"At [Company], we believe..." — just state the belief
"Streamline" — everyone is streamlining, stop
Filler transitions: "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..." — be direct, just start

绝对不要使用以下表述，出现即视为不合格：

「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...」——直接切入主题，不要铺垫

The Opening (First 2-3 Sentences)

开篇（前2-3句话）

The opening must do one of two things: state the problem or state the conclusion. Never start with background, company history, or hype.

Good: "Two weeks before launch, we killed our entire metrics product. Here's why pre-aggregating time-series metrics breaks down for debugging, and how we rebuilt the system from scratch."

Bad: "At Sentry, we're always looking for ways to improve the developer experience. Today, we're thrilled to share some exciting updates to our metrics product that we think you'll love."

开篇必须二选一：点明问题 或者 给出结论。绝对不要以背景介绍、公司历史、营销话术开头。

正面示例： "上线前两周，我们砍掉了整个指标产品。本文将解释预聚合时序指标为什么不利于调试，以及我们如何从零重构了这套系统。"

反面示例： "在Sentry，我们一直致力于优化开发者体验。今天我们非常激动地分享指标产品的重磅更新，相信大家一定会喜欢。"

Structure: Follow the Reader's Questions

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

Structure every post around what the reader is actually wondering, not your internal narrative:

What problem does this solve? (1-2 paragraphs max)
How does it actually work? Not buttons-you-click, but underlying technology. (Bulk of the post — be specific)
What were the trade-offs or alternatives? (This separates good from great)
How do I use/try/implement this? (Concrete next steps)

For engineering deep-dives, also address: 5. What did we try that didn't work? (Builds trust) 6. What are the known limitations? (Shows intellectual honesty)

所有博文的结构都要围绕读者真正关心的问题来设计，而不是你的内部叙事逻辑：

这解决了什么问题？（最多1-2段）
它的实际运行原理是什么？ 不是讲点击哪个按钮，而是底层技术逻辑。（博文核心内容，要足够具体）
过程中有哪些取舍，或者考虑过哪些替代方案？（这是优秀博文和普通博文的区别）
我要怎么使用/试用/落地它？（给出可落地的后续步骤）

如果是工程深度解析类内容，还要补充： 5. 我们试过哪些行不通的方案？（建立读者信任） 6. 已知的局限性有哪些？（体现内容的诚实性）

Section Headings Must Convey Information

章节标题必须传递有效信息

Weak: "Background," "Architecture," "Results," "Conclusion"

Strong: "Why time-series pre-aggregation destroys debugging context," "The scatter-gather approach to distributed GROUP BY," "Where this breaks down: the cardinality wall"

反面示例： "背景"、"架构"、"成果"、"结论"

正面示例： "为什么时序预聚合会丢失调试上下文"、"分布式GROUP BY的scatter-gather实现方案"、"方案失效场景：基数墙"

Technical Quality Standards

技术质量标准

Numbers over adjectives. If you make a performance claim, include the number.

Bad: "This significantly reduced our error processing time."
Good: "This reduced our p99 error processing time from 340ms to 45ms — a 7.5× improvement."

Code must work. If a post includes code, test it. Include imports, configuration, and context. Comments should explain why, not what.

Diagrams for systems. If you describe a system with more than two interacting components, include a diagram. Label with real service names, not generic boxes.

Honesty over hype. Never overstate what a feature does. Acknowledge limitations. If something is in beta, say so. If a competitor does something well, it's okay to note that. Do not claim AI features are more capable than they are — "Seer suggests a likely root cause" ≠ "Seer finds the root cause."

用数据代替形容词。 如果你提出了性能相关的结论，必须附上具体数据。

反面示例："这大幅缩短了我们的错误处理时间。"
正面示例："这把我们的p99错误处理时间从340ms降到了45ms——提升了7.5倍。"

代码必须可运行。 如果博文中包含代码，要经过测试。要包含导入语句、配置和上下文说明。注释要解释为什么这么写，而不是写了什么。

系统需要配架构图。 如果你描述的系统包含超过2个交互组件，要附上架构图。要用真实的服务名称标注，不要用通用的方框占位。

诚实大于营销。 绝对不要夸大功能的作用，要主动说明局限性。如果功能还在beta阶段，要明确说明。如果竞品有做得好的地方，也可以提及。不要夸大AI功能的能力——「Seer会给出可能的根因建议」≠「Seer能找到根因」。

Title Guidelines

标题规范

The title is the highest-leverage sentence in the post. It must stop a developer scrolling through their RSS feed or Twitter.

Strong titles make a specific claim, tell a story, or promise a specific payoff:

"The metrics product we built worked. But we killed it and started over anyway"
"How we reduced release delays by 5% by fixing Salt"
"Your JavaScript bundle has 47% dead code. Here's how to find it."

Weak titles are vague announcements:

"Introducing our new metrics product"
"Performance improvements in Sentry"
"AI-powered debugging with Seer"

标题是博文里杠杆效应最高的一句话，必须能让刷RSS feed或者Twitter的开发者愿意停下来看。

优秀标题 会给出具体的结论、讲一个故事，或者承诺明确的收益：

"我们做的指标产品本来能跑，但我们还是砍掉重来了"
"我们是怎么通过修复Salt把发布延迟降低了5%的"
"你的JavaScript包有47%的死代码，教你怎么找出来"

不合格标题 都是模糊的公告类内容：

"介绍我们全新的指标产品"
"Sentry的性能优化更新"
"Seer：AI驱动的调试能力"

The Closing

结尾

End with something useful — a link to docs, a way to try it, a call to give feedback. Never end with generic hype ("We can't wait to see what you build!") or recaps of what you just said.

结尾要给出有用的内容——文档链接、试用入口、反馈收集通道。绝对不要用空泛的营销话术结尾（"我们非常期待看到你的创作！"），也不要复述前面已经讲过的内容。

Post Types

内容类型

Here's the quick map by post type:

Type	Goal	Byline
Engineering Deep Dive	Explain a technical system/decision so other engineers learn	The engineer(s) who built it. Always.
Product Launch	Explain what shipped, why it matters, how to use it	PM, engineer, or DevEx. Not PMM unless marketing built it.
Postmortem	Transparent failure analysis with timeline and fixes	Engineering leadership
Data / Research	Original insights from Sentry's unique data position	Data team, engineering, or research
Tutorial / Guide	Help a developer accomplish something specific	DevEx, engineer, or community contributor

以下是不同内容类型的快速对照表：

类型	目标	署名
工程深度解析	解释技术系统/决策，让其他工程师能从中学习	必须是参与开发的工程师
产品发布	说明上线了什么、为什么重要、怎么使用	产品经理、工程师或开发者体验团队成员，除非是营销团队做的功能，否则不要由产品营销经理署名
Postmortem	透明的故障分析，包含时间线和修复方案	工程管理层
数据/研究	基于Sentry独有的数据优势产出的原创洞察	数据团队、工程师或研究人员
教程/指南	帮助开发者完成某个具体的任务	开发者体验团队、工程师或社区贡献者

The "Would I Share This?" Test

「我会分享这篇吗？」测试

Before publishing, ask: Would a developer share this post? Does it have a shot at getting on Hacker News? If the answer is no, the post either needs more depth, more original insight, or it belongs in the changelog instead.

Posts worth sharing contain at least one of:

A technical decision explained with trade-offs
Original data or research not found elsewhere
A real-world debugging story with specific details
An honest accounting of something that went wrong
A how-to that saves the reader real time

发布前先问自己：会有开发者愿意分享这篇博文吗？它有机会登上Hacker News吗？如果答案是否定的，说明这篇博文要么不够有深度，要么缺乏原创洞察，应该放到更新日志里而不是博客。

值得分享的博文至少包含以下一点：

带取舍说明的技术决策解析
别处找不到的原创数据或研究
有具体细节的真实调试故事
对出错内容的诚实复盘
能实实在在帮读者节省时间的实操指南

Non-Negotiables (Quick Reference)

硬性要求（快速参考）

Never publish without a real person's name on it. No "The Sentry Team" bylines.
Never publish code that doesn't work.
Never say "we're excited to announce." Just announce it.
If you describe a system, include a diagram.
If you make a performance claim, include the number.
If you discuss a decision, explain what you didn't choose and why.
Every post must have a clear "who is this for" in the author's mind before writing.
Changelogs belong in the changelog. Blog posts should offer something more.
When in doubt, go deeper. The risk of being too shallow is far greater than being too detailed.
Write the post you wish existed when you were trying to solve this problem.

绝对不要发布没有真实个人署名的内容，不要用「The Sentry Team」作为署名
绝对不要发布不能运行的代码
绝对不要说「我们非常激动地宣布」，直接公布内容
如果你描述了一个系统，必须附上架构图
如果你提出了性能相关的结论，必须附上具体数据
如果你讨论了某个决策，要说明你放弃了什么方案，以及为什么
写之前作者必须明确这篇博文的受众是谁
更新日志的内容放到更新日志里，博文要有更多额外价值
不确定的话就写得更深入，内容太浅的风险远高于内容太细的风险
写你自己当初遇到这个问题时，希望能找到的那篇博文

When Reviewing or Editing a Draft

当审核或编辑草稿时

Run through both checklists:

Technical Review:

All technical claims accurate
Code samples work
Architecture descriptions match reality
Numbers and benchmarks correct
No oversimplifications that would make an expert cringe

Editorial Review:

Opening hooks reader within 2 sentences
Passes the "would I share this?" test
No corporate language, filler, or fluff
Headings convey information
Right length (not padded, not too thin)
Title is specific and compelling

Final Check:

Author byline is correct (real person's name)
Links to docs/getting-started included
Post doesn't duplicate what's in the changelog

When providing feedback, be specific and constructive. Quote the weak passage, explain why it's weak, and rewrite it to show the standard.

要对照以下两个检查清单：

技术审核：

所有技术表述准确
代码示例可运行
架构描述和实际情况一致
数据和基准测试结果正确
没有会让专家觉得尴尬的过度简化内容

内容审核：

开篇2句话内就能吸引读者
通过「我会分享这篇吗？」测试
没有企业套话、填充内容或空话
标题能传递有效信息
长度合适（没有凑字数，也不会太单薄）
标题具体有吸引力

最终检查：

作者署名正确（真实个人姓名）
附上了文档/入门指南的链接
内容没有和更新日志重复

给出反馈时要具体、有建设性。引用不合格的段落，说明哪里不好，再重写一段作为标准参考。