developer-case-study

开发者案例研究

你正在撰写他人的工程故事。开发者案例研究要说明：这些工程师在生产环境中运行了这项技术、发生了哪些变化，以及他们付出了什么代价。读者是正在评估这项举措能否适用于自己系统的工程师，而不是寻求保证的潜在客户。

这样的读者一眼就会对只有好处的叙述打折扣。你的说服力来自严谨地对待证据，并诚实讲述其中棘手的部分，而不是文字修饰。

范围检查

开始前确认材料类型。遇到以下情况时，请转到其他类型：

• 系统是你自己的，没有外部采用者参与 → 工程博客文章技能。
• 这是你自己的项目进展，并在进行过程中分享 → 公开构建技能。
• 读者需要学习或安装某项内容 → 教程或快速入门技能。
• 材料讲的是“v2.4 发布了什么”或“如何从 v1 迁移到 v2” → 更新日志或迁移指南技能。
• 用户想要一篇介绍_他们_所做工作的作品集文章 → 这是个人案例研究，主角是作者。请说明这一点；此技能采用相反的视角。

确切标识符请参阅“参考资料”部分。

访谈

在接触故事内容前，先逐个向案例研究负责人提出以下问题；可以采用选择题的地方就采用选择题。一旦能够判断故事是否适合发布，就立即停止。

记忆：记录一些当前任务或项目背景信息。如果记忆存储在文件中，请使用 devrel-context.md；如果使用其他记忆系统，则使用该系统。将不同任务的信息放在不同的章节中。任务完成后将其删除。为任务添加日期；一般项目背景无需日期。部分访谈回答可能会因任务不同而有所差异。

1. 谁是采用者？目前已在生产环境中使用，还是仍在评估阶段？
2. 你要采访谁？他们的实际工作职责是什么？是否也能联系到他们的经理或平台负责人？
3. 你这边现有哪些证据——支持工单、迁移问题或 PR、使用情况遥测数据、客户的账户记录、他们自己的博客文章或演讲？
4. 具体有哪些变化？用数字说明。客户团队内谁能为这些数字作证？
5. 谁能批准公开公司名称、人名和使用徽标？每项审批需要多久？
6. 客户一方是否需要进行安全或法律审查？是否已经有人启动了这些流程？
7. 这篇内容发布在哪里？是否还需要制作一页式销售版本？
8. 读者读完后，你希望他们能复述给同事的一句话是什么？
9. 必须在哪个日期前发布？届时会发生什么？如果截止日期在本月内，任何仅法律审查就会耗时更长的企业客户候选对象都会被排除，而能通过一条消息批准的采用者则会优先。
10. 这是一次性成果——为一个停滞的交易制作一篇案例研究——还是要持续补充的案例库？一次性成果应优先选择最接近获批的候选对象；案例库则应优先填补覆盖表中的空白项，即便该案例是最难快速完成的。
11. 投入的工作量上限是多少？要把客户花费的时间和善意也计入，不能只算你这边的投入。若仅能安排一次访谈和一轮审阅，就不适合讲多方参与的企业故事；若客户团队愿意投入一个季度的人际关系资本，则可以考虑这类故事。

如果你的运行环境支持持久化记忆，请保存第 5、6 和 7 个问题的答案。这些是针对每位客户和每个项目的约定，在你为他们撰写的每篇故事中都会保持不变。

工作流

1. 根据以下门槛评估故事；若有多个候选采用者，在为任何一个投入一小时之前，先用“优先追踪哪个故事”对他们排序。在这里淘汰或降级——未通过门槛的故事无法靠编辑挽救。
2. 先用你自己的证据还原故事。 通话前先阅读工单、问题、PR 和遥测数据，这样你带着具体内容来确认，而不是带着开放式提示来填空。
3. 并行启动审批流程。 阅读合同中的宣传条款，然后在起草前询问由谁批准引言、指标和安全审查——他们的答复将决定故事可以写成哪个版本。
4. 进行来源访谈。 遵循 ./references/source-interview-guide.md。征得同意后录音，并保留文字记录。
5. 建立证据台账。 研究中每项主张占一行：主张、证据类别、所依据的工具，以及谁能够重新推导出该结果。起草前完成这一步。
6. 与负责人确认主线和关键数据。 现在修改成本低，写完 1,200 字后修改成本就高了。
7. 按照 ./references/case-study-outline.md 中的主线起草，引言须与文字记录逐字一致。
8. 根据访谈中关于成本和未解决工作的回答撰写局限性部分。 绝不能跳过——见下文。
9. 进行人性化润色，然后通过发布门槛。 反复修改，直到每项检查都通过。
10. 发送审批，附上标明的待决事项清单和明确的截止日期，参见 ./references/approval-and-anonymization.md。应用对方的修改，然后整理衍生版本。

调用示例

• “我们刚完成将 Northwind 的计费流水线迁移到我们的工作流引擎。写一篇案例研究。” → 从第 1 步开始执行完整工作流。
• “这是我与他们的资深工程师通话的文字记录，还有一张指标截图。起草吧。” → 跳到第 5 步；根据文字记录建立证据台账，并标出文字记录无法支持的每项主张。
• “法务回复说不能写公司名称。现在怎么办？” → 跳到匿名化阶梯，提出下一档方案，并说明其代价。
• “这个故事值得写吗？” → 仅运行资格门槛检查，并给出结论和未通过的门槛。
• “有四位客户都同意了，应该选谁？” → 按“优先追踪哪个故事”中的排序方法，逐一评估这四位客户；受其限制而无法采用的客户应直接剔除，而不是排在最后。
• “把已获批准的 Northwind 研究改成一页销售材料。” → 仅制作衍生版本；先确认现有审批是否涵盖新的呈现形式。

除非用户另有要求，否则按以下顺序交付六部分：

1. 结论行——可发布、可按 X 形式发布，或暂不可发布，并说明原因。
2. 证据台账——每项主张占一行：主张、类别、工具、时间范围、谁能重新推导出该结果。
3. 草稿——八部分主线，引言逐字引用，并包含局限性。
4. 审批材料——标明待确认的决定，并附上建议的截止日期和默认方案。
5. 门槛报告——七项检查逐项列出通过或未通过，以及已采取的修正措施。
6. 衍生版本——一页材料或其他用户要求的版本，仅在获得批准后提供。

起草之前先给出结论和台账。在正文写完后才建立的台账，不过是在为正文寻找理由。

故事筛选门槛

五道门槛——这是本技能自己的清单，并非已发布的标准。一个可发布的故事必须全部通过：

• 已投入生产，而非试点。 有真实流量，也有真实后果。评估至多只能算一则用户评价。
• 有经过衡量的使用前状态。 没有基线，就无法诚实地说明变化，只能凭感觉。
• 有一位愿意出面交流的人。 没有可引用的人，就没人会相信。
• 读者可以借鉴的决策。 已考虑过备选方案，并基于明确的理由选定了一个。
• 有可行的审批路径。 确实有人能授权使用公司名称，或批准可行的匿名版本。

未通过一道门槛，并不总意味着不能写成故事：

• 缺少生产环境：等一等。
• 缺少基线：发布规模或架构方面的故事，不声称有变化。
• 缺少批准：沿匿名化阶梯逐级处理。
• 缺少当事人：这是一篇工程实践文章，不是案例研究。坦率说明这一点，不要刻意包装成案例研究。

应该先追逐哪类故事

当有多个采用者都能支撑一项研究时，选择的关键不是谁最令人印象深刻，而是谁能以最少的投入时间带来最多已发布的证明，同时把客户自己的时间和善意视为最稀缺的投入。采用者类型可以预测这个比率的两方面，因此应据此排列候选对象，并按以下顺序推进。

• 效率（每小时追逐投入能带来的已发布证明——默认顺序）：初创公司或规模化公司 > 个人开发者或 OSS 维护者 > 消费产品工程团队 > 企业
• 投入（从最费力到最省力，计入客户的时间和善意）：企业 > 消费产品工程团队 > 初创公司或规模化公司 > 个人开发者
• 价值（对尚未做出决定的读者来说，证明力从强到弱）：企业 > 消费产品工程团队 > 初创公司或规模化公司 > 个人开发者
• 合规成本（从审查最繁重到最轻）：企业 > 消费产品工程团队 > 初创公司或规模化公司 > 个人开发者

价值这一项假设读者是在为公司内部的团队做评估。如果产品的采用者本身是独立开发者和维护者，这个排序就会反过来——此时，独立开发者的故事是最有力的证明，而企业故事读起来则无关紧要。采用默认排序前，先根据实际购买者重新排列。

按效率排序，以下说明了每种类型的成本、收益，以及由此要求的写作方式：

1. 初创公司或规模化公司的 B2B 采用者——只需一两个人审批，耗时一周。清单中投入产出比最高，但风险与企业案例正好相反：没人核查数据。发布前自行核实，重复使用前再次核实——小公司可能会转型，也可能迁移离开。
2. 个人开发者、独立创业者或 OSS 维护者——审批成本几乎为零；一条消息就能征得同意，而这个人_本身就是_品牌。指标体现的是个人规模（构建所需分钟数、托管账单、一整个周末的工作），在这个规模下完全可信——绝不要把它们夸大成企业级表述。明确询问他们是否希望提及其雇主。
3. 消费产品工程团队（B2C 产品，开发者故事）——团队设有传播职能，但故事不会涉及他们自己的用户，因此审核范围比企业案例窄。采用者的用户不会读到这篇故事；受众是同行工程师。应更深入地探讨架构和规模化机制，并完全删去面向买家的商业叙事。
4. 企业 B2B 采用者——需要一个季度，期间要经历数周审查；传播团队掌控叙事；绝对数值会被大幅删改；安全审查后还要再审一轮。起草前先联系法务。他们的工程师会阅读这篇故事，因此准确性问题会经由客户团队反馈回来。 这种排序会挤掉具名的企业级生产环境参考案例：对于需要在内部为选择提供依据的读者来说，这是最有力的证明；而且在法律审查和客户善意方面，它也是清单上代价最高的案例。效率排名每个季度都会把它往后排，案例库也因此塞满了无法推动企业级评估的小案例。当正在进行的交易因缺少同等规模的同行参考案例而陷入停滞，或覆盖表中的企业级一行为空时，应将它提到所有内容之前——这个缺口没有廉价的替代方案，三个初创公司案例也抵不上一个企业级案例。

删除，而不是降级。客户的法务团队不批准公开引用时，应将其从候选名单中删除，而不是放在末尾。只有匿名化阶梯中的某一级仍能通过资格门槛时，才保留该客户。

否则，这个候选案例就不复存在：“也许下个季度”的名字会继续消耗客户团队的沟通请求，以及随之而来的关系资本。仍在评估阶段而非生产环境中的候选案例也应同样删除，因为它未能通过第一道门槛，等待它并不是计划。

这种排序是默认规则，而非铁律：它会随具体情况和追寻案例的人而变化。

• 如果客户团队已经与某家企业建立了良好关系，那么这个案例的大部分成本已经付出。
• 如果某位维护者已经公开撰写过有关产品的内容，那么在有人联系之前，案例研究就已经完成了一半，距离发布也不远。

数字规范

每个数字都必须包含以下四项属性，否则就不能发布：

• 之前的数值。
• 之后的数值。
• 得出该数值的测量工具。
• 测量时间范围。

证据类别	现有信息	撰写方式
实测	同一测量工具得出的前后数据	直接陈述，并注明测量工具和时间范围
部分实测	之后的数值经过测量，之前的数值为估算	陈述数值，并标明估算值
客户报告	客户提供的数值，未经测量	注明来源：“团队估算……”
方向性	只保留了定性说法	删除数字；改用工程师自己的说法

两个来源可靠的数字胜过六个不严谨的数字。当客户不批准绝对数值时，比例比绝对数值更容易传播（“基础设施成本降低了三分之一”）；周期时间和可靠性数据也比原始数量更容易传播，因为读者无需了解客户的规模，就能与自己的系统进行比较。

不要：

• 计算客户未确认的数字。
• 将一个月的结果年化。
• 在客户同时改变了三件事时，把业务成果归因于你的产品。应说明还有哪些改变。

对这项技能本身使用的数字，也应遵守同样的规则。./references/evidence-and-sources.md将本文中的每个阈值区分为有来源或自行设定。引用自行设定的基线时，只能将其作为工作基线——绝不能把它当作行业标准告诉采用者。

核心框架

已发表的研究都采用 挑战 / 解决方案 / 结果：四个独立案例都包含相同的三个部分——两个供应商研究和两个通用营销技能模板（来源见 ./references/evidence-and-sources.md）。保留这些部分，并补上模板遗漏的三项：被否决的替代方案、指标来源和局限性。

以下字数预算是自行设定的比例，目标总字数为 1,200-1,800 字——这个目标本身也是自行设定的，选择它是为了略低于三项经过测量的供应商研究（约 1,650、约 2,100 和约 2,400 字；均未专门设立局限性章节）。根据材料调整比例。

1. 核心成果——变化的数值和幅度（约 60 字）
2. 采用者和相关系统（约 120 字）
3. 原有状况及其代价（约 250 字）
4. 为什么选择这项技术——权衡并否决其他方案（约 200 字）
5. 构建内容——架构、具名组件、实施顺序（约 400 字）
6. 结果——数值及测量方法（约 200 字）
7. 付出的代价和仍未解决的问题（约 200 字）
8. 下一步计划（约 70 字）

第 4、5 和 7 节是此类案例与用户证言的区别所在。如果材料只能填满第 1、2、6 和 8 节，那你写的就是一张引言卡片——就按这个形式发布。

起草前，请阅读 ./references/case-study-outline.md，了解各节的具体指导以及正反实例。文中的示例（Acme、Grafana 数据）都是虚构的示例，并非经过测量的案例——切勿将其作为证据引用。

局限性才是差异所在

局限性是读者采用后也会承担的代价，而不是计划。

Roadmap: "We plan to consolidate the two languages."
Cost:    "We shipped the orchestration layer in Go while the rest of the team
          writes Python, and that split is now a hiring constraint."

一项对比研究列出了三项前者，却没有列出任何后者——不要接受这种取舍。

差距源于出版方的选择，而非体裁限制。在对比的四项研究中——样本量很小，且两项供应商研究都来自同一家供应商：

• 供应商发布的两项研究完全没有披露成本。
• 社区发布的两项研究则公开披露了成本和一次失败，其中一项由一位具名从业者讲述自己失败的上线经历。

章节清单和来源见：./references/evidence-and-sources.md。

根据访谈内容填写本节：

• 迁移所需的工程师周数。
• 双轨运行的持续时间。
• 推出过程中出现的故障。
• 团队接受了哪些再培训。
• 他们有意保留、没有迁移的工作负载。
• 哪些方面仍然无法正常工作。

明确说明哪些人不应该照搬这一架构。

• 客户删掉整节：研究质量会变弱，但仍可发布。
• 客户既删掉本节_又_删掉替代方案一节：你发布的就是一则广告。明确告诉负责人，以便将其按广告形式呈现。

审批流程

在向任何人提出请求前，先阅读合同中的宣传条款。标准的自助式 SaaS 条款通常已经授予使用客户名称和徽标，以及声明其为客户的许可——Vercel 的条款就包含这样的条款，原文引述见 ./references/approval-and-anonymization.md。

该条款不授予其他任何权限：

• 不允许引用。
• 不允许使用指标。
• 不允许描述架构。
• 不允许讲述客户如何运行其系统。

只针对条款未涵盖的内容提出请求。

通常有四项权限，分别由四个不同的人掌握：

• 工程师同意接受引用。
• 其经理同意动用团队的信誉。
• 传播部门批准使用公司名称和徽标。
• 安全或法务部门审查技术细节。

初次联系时，就询问每项权限由谁负责。

提前删去安全审查中可预见会被删掉的内容：

• 基础设施的绝对规模和成本。
• 内部服务名称、工单 ID、仪表板 URL。
• 被拒替代方案部分中的竞争对手名称。
• 任何暗示事前状态存在安全弱点的内容。

发送完整草稿，标明需要决定的事项、注明日期的截止时间，以及逾期未回复时的默认处理方式。

如果对方拒绝具名，就沿着匿名化阶梯逐级往下，而不是放弃这个故事：

1. 具名公司和工程师。
2. 具名公司，工程师不具名。
3. 公司不具名，但提供可识别的描述。
4. 仅提供类别描述。
5. 不涉及客户的模式总结。

每降一级都会损失可信度，最后一级已不再是案例研究。

这套阶梯刻意不按工作量或效率排序：这些级别并不是任人挑选的替代方案，因为最高级别以下的每一级之所以更容易做到，只是因为有人拒绝了上一级。应争取审批允许的最高级别，并将逐级下降视为损失，而非权衡取舍。

完整阶梯、删减类别和请求模板：./references/approval-and-anonymization.md。

人性化处理

在进入审核环节前，使用你偏好的 humanizer 技能润色文案。带有模型腔调的填充内容读起来像供应商宣传文案，而这正是这份材料最需要避免的风格。

以下内容必须原样保留：每一处引用、每一个数字、版本字符串、组件名称和架构描述。经过人性化处理的引用就是捏造的引用。

发布审核关卡

七项检查——这是一个实际使用的关卡，并非已发布的标准。七项全部通过前，不得发布研究报告。说明哪项检查未通过以及做了哪些修改，然后重新检查。

1. 每项声明都经过分类——实测、部分实测、报告所得，或由工程师标记的观点。无一例外。
2. 每个数字都有对应的测量工具和时间窗口，且已注明或一键即可查看。
3. 至少发布一项限制，并且足够具体，让读者能够据此决定不选择你们。
4. 包含替代方案部分，说明拒绝了什么以及原因。
5. 每一处引用都与访谈记录逐字一致，并署以已确认的姓名和职务。
6. 公司名称、徽标、引用和安全审查均有审批记录存档。
7. 没有任何缺乏依据的最高级表述。 任何“无缝”“毫不费力”“变革性”等说法，要么由研究报告中的数字支撑，要么删除。

发布前还需进行两轮人工审阅：

• 受访工程师确认技术准确性。
• 一位项目之外的人检查内容是否无需内部术语也能理解。

衍生版本

一项获批的研究可以产出多种材料。请在审批前确认需要哪些材料，确保授权范围涵盖这些用途，并按每小时复用价值排序制作——以下每一项都会复用已获批研究中的材料，因此排序依据是复用后的价值，而非撰写所需的工作量：

1. 文档交叉链接——几乎不费工夫：在相关页面添加一条“谁在使用以及如何使用”的链接，放在评估者本来就会阅读的位置。
2. 一页式销售摘要——约一小时：包含成果、三个数字和一条引言，每个部分都不加行动号召。只要存在销售流程，它就是四项中价值最高的；若没有销售流程，则毫无价值——这种情况下恰恰应该跳过，而不是给它排序。
3. 社区帖子——约一小时，外加工程师愿意参与：由工程师以自己的名义用自己的话撰写，比任何以你的名义发布的内容传播得都远，而且只有工程师本人能授权发布。
4. 会议或网络研讨会材料——半天，且前提是已经有演讲机会。架构变更前后的对比已经可以直接作为一张幻灯片，因此额外成本很低；但在演讲获批之前，这些材料都无法发挥作用。

将研究中的各个要素——每项指标、每条引言、架构图——连同完整叙述一起存入证据库，并标明公开或私有。之后制作的材料直接取用这些要素；没人需要重读一篇 1,500 字的研究报告来找一个数字。

在付费或广告场景中重新发布通常需要单独授权。重新使用大约超过 18 个月的研究前，请再次核实——这只是自行设定的惯例，并非基于测得的有效期；对于快速发布或频繁迭代的采用者，应缩短期限。

常见失败模式

症状	原因	修正
读起来像一篇客户证言	只有第 1、2、6、8 节有内容	回头补充替代方案、架构、成本——或发布引言卡片
客户删掉一半数字	指标从未记录来源	为每项指标补上测量工具和时间窗口，重新提交
审批停滞数周	起草后才启动审核流程	首次联系时就启动审批流程；设定一个有日期的默认方案
工程师公开质疑内容	架构描述基于供应商的假设	请受访工程师确认技术部分
引言听起来像营销文案	进行了转述，而非逐字转录	根据录音恢复原话；接受客户自行修改的版本
采访后案例就没了	跳过了资格筛选关卡	预约通话前先完成筛选
数字夸大了成效	将多项变更的成果归功于产品	列出同一时间窗口内发生的所有其他变更
客户质疑一项“已获批”的研究	将合同中的徽标条款理解为全面授权	将该条款仅视为对名称和徽标的授权；引言、指标和叙述需分别取得授权
局限性一节没有实质内容	将路线图项目当成成本接受	再次询问工程师投入周数、双轨运行情况以及出了什么问题——计划不等于成本
已流失客户的研究仍在线上	发布时未设定重新核实日期	为每项研究注明日期，按计划重新核实；若不再适用，就下架，而不是继续保留

衡量

评判一项研究时，应看它是否推动了评估进程，而不是看流量。目前没有已发表的指标能单独衡量专门面向开发者的案例研究：一般的 B2B 技术买家研究显示，就影响购买决策而言，供应商制作的案例研究远不如产品演示和免费试用（参见 ./references/evidence-and-sources.md），但没有更具体的研究。以下信号应作为权衡依据，而不是要达成的目标：

• 在实际交易中的使用情况：销售人员或解决方案工程师实际发送案例的频率，以及发送时所处的阶段。
• 阅读完成率，以及读者点击案例所链接资料（文档、代码库、架构页面）的情况。
• 主动索要推荐：潜在客户要求与该客户交流。
• 采用方是否主动传播案例；客户自己的工程师愿意分享的故事，才是他们认可的故事。
• 故事库的覆盖范围：每种主要用例和采用方规模都有一个可信案例，胜过同一类型的五个案例。

不要将营收归因于单个案例研究。过度声称归因效果，与案例研究旨在避免的可信度问题如出一辙。

参考资料

• samber/developer-relations-skills@tech-talk-outline - 将获批的研究转化为演讲
• samber/developer-relations-skills@technical-video-script - 将获批的研究改编为视频
• samber/developer-relations-skills@tech-podcast-interview-prep - 将获批的研究改编为播客
• samber/developer-relations-skills@devrel-content-calendar - 规划一个季度内故事库的发布安排
• samber/developer-relations-skills@tech-press-relations - 向记者推介获批的案例研究，作为新闻报道素材
• ./references/source-interview-guide.md - 通话前准备、问题递进设计、引语采集
• ./references/case-study-outline.md - 分章节大纲和完整示例
• ./references/approval-and-anonymization.md - 同意审批流程、删改类别、匿名化层级、请求模板
• ./references/evidence-and-sources.md - 支撑核心内容的已发表研究，以及有来源依据与自行设定的阈值