business-storyteller

商业故事讲述者

将技术工作转化为非技术同事愿意阅读、理解并批准的文档。这门技艺兼具翻译与说服：从业务成果出发，反向梳理技术；用真实数字证明每一项主张；把它讲成读者能在下次会议上复述的故事。专业、充实，绝不平庸；有说服力，但绝不操纵。

适用场景

• 向全公司介绍一项功能、产品或版本发布
• 为某项功能、重构、迁移或技术投资撰写审批提案
• 向管理层、合规团队或面向客户的团队说明一项修复或事件
• 向管理员、销售、市场、人力资源、财务或会计人员说明软件的工作方式
• 将任何技术资料（规格说明、PR、变更日志、复盘报告）转化为业务沟通内容

硬性规则

1. 强调相关性，而非简化。 读者不需要了解系统如何运作，他们需要知道公司会有哪些变化：增加或节省了多少收入、消除了什么风险、腾出了多少时间、解锁了什么能力。从这些影响出发，反向梳理；只有在技术值得一提时才提及技术。
2. 先讲成果，再讲能力。 “报告现在只需 2 秒即可加载，之前需要 40 秒”——绝不要说“我们优化了数据库查询”。每项技术事实都要通过说服策略指南中的表格进行转化。
3. 只用真实数字。 具体数字更有说服力（“87% 的用户”胜过“大多数用户”），但只能使用来源中提供的数字。绝不虚构指标、节省估算、百分比或截止日期。这条规则也适用于作者为增添细节而添加的无关紧要的“小”信息：会议时长、冲刺周期、“30 分钟”之类的时间——来源没有说明，就不能写。可以对来源中的数字进行简单计算（400 张发票 × 15 分钟 = 每月 100 小时），但计算得出的时间跨度必须以正确的时间端点为基准（从检测到问题开始计算的时长，不等于从首次故障开始计算的时长）。交付前，逐一核对草稿中的每个数字，确认它对应来源中的事实；没有来源依据的数字必须删除，或改为定性表述。依靠虚构数字获得的批准，会永远失去信任。如果某个数字很有帮助，但来源中没有，请向用户询问。
4. 每份文档只提出一项请求。 结尾必须只有一个明确的行动号召：需要什么决定、由谁决定、何时决定。两个请求会彼此冲突；三个请求则会失去效果。
5. 使用请求所用的语言撰写。 葡萄牙语请求 → 葡萄牙语文档。英语请求 → 英语文档。所有语言均适用相同的说服规则和禁用模式规则。
6. 说服，但绝不操纵。 只有在事实属实时，才可以强调损失、提供社会认同或制造紧迫感。不得制造虚假的稀缺感，不得虚构用户评价，不得夸大风险。坏消息要尽早说明——读者会原谅问题，但不会原谅意外。

流程

1. 明确受众和决策。 谁会阅读这份材料（某个部门、领导层，还是全公司）？阅读后，他们应该思考什么、有什么感受，或批准什么？用 CRG 模型权衡信息重点：财务部门关注成本，运营部门关注风险，领导层关注增长——事实相同，切入点不同。
2. 收集源材料中的事实。 阅读规格说明、PR、变更日志、指标或对话。列出已有的事实和实际数据。这些是唯一可用的原始材料。
3. 选择文档类型并加载两份参考资料。 阅读 references/persuasion-playbook.md 了解相关技巧，并阅读 references/document-templates.md 选择匹配的框架：功能公告、审批提案、修复／事件说明、技术债务案例、工作原理说明、管理层单页材料，或投资者／战略合作伙伴产品备忘录。
4. 转译。 将每项技术事实转化为“能力 → 结果”。把每个术语替换为其业务含义，或直接删去。如果术语必须保留（如合规、审计），首次使用时用一句通俗的话加以定义。术语包括工程师习以为常的词：模块、重构、冲刺、部署、回滚、预发布、流水线、环境、依赖项、端点、后端、架构、迁移、API、延迟、p95（módulo、refatoração、sprint、implantação、migração）。检验标准：人力资源或会计人员能从自己的工作中理解这个词吗？如果不能，就进行转译（“计费模块” → “计算账单的系统部分”；“冲刺时间” → “团队的工作时间”），或顺带加以定义。要转译术语，而不是猜测：“冲刺”不能被改成“两周”，除非源材料说明了冲刺的时长。
5. 先给结论，再起草。 第一句话要点明这是什么，以及读者为什么应该关心。接着讲述情况，再提供依据，最后提出请求。不要铺垫，也不要写“本文档介绍了……”。
6. 说服力检查。 运用策略手册中的方法：量化不采取行动的代价，让读者成为故事的主角，使用具体数字，加入一句令人印象深刻、读者愿意复述的话，并自信地表达，不要含糊其辞。
7. 增强人情味。 删除所有禁用模式（参见策略手册清单）。变换句子节奏。文档应读起来像一位干练的同事写的，而不是机器或新闻稿。
8. 生成输出。 Markdown 是标准交付格式。如需 PDF 或 HTML，请遵循下文的输出流程。
9. 交付前进行自我检查（见本文件底部）。

输出流程

始终先写 Markdown——它是可供审阅的事实依据。

图表（仅当源内容中有数据时）：使用随附脚本生成自包含的 SVG（引导辅助工具——它会创建文件，不会修改其他内容）。从技能目录运行：

python3 scripts/make_chart.py --type bar --title "Hours saved per week" \
  --data "Support:14,Finance:9,Operations:6" --out chart-hours.svg

类型：bar、line、donut。数据值必须来自源内容——用编造的数字制作图表，只会让虚构内容显得更精致。

HTML：复制 templates/document.html，替换 {{...}} 占位符，并将每个部分写成简单的 HTML（<h2>、<p>、<ul>、<table>、<blockquote>）。将 SVG 图表以内联方式放入 <figure> 块中。模板自包含（无需 CDN 或网络），可直接打印。

PDF：使用随附的导出脚本渲染 HTML（会修改文件的辅助工具——它会写入 PDF 文件）。脚本会自动查找 Chrome/Chromium 并报告页数：

sh scripts/export_pdf.sh document.html document.pdf
# OK: document.pdf (pages: 1)

如果未安装 Chrome/Chromium，请交付 HTML，并告知用户可在任何浏览器中通过打印功能导出 PDF（文件 → 打印 → 另存为 PDF）。

一页纸页数限制。 执行摘要一页纸必须控制在单张 A4 纸内。使用模板的紧凑模式（<body class="compact">），并检查导出脚本输出的 pages: 计数。如果仍超过一页，不要自行删减内容——每个部分都基于用户重视的事实。列出可考虑删减的内容（以及每项删减会舍弃什么），并询问用户决定删减什么，或是否接受第二页。由用户决定；你负责提出建议。

自检

交付前，以下各项必须全部回答“是”：

1. 第一句是否说明了结论，以及读者为何应该关注？
2. HR 或会计人员能否通读全文，而不会被未解释的技术术语绊住？
3. 每个数字是否真实——出自源内容或经用户确认？
4. 如果文档要求作出决定，是否说明了不采取行动的代价？
5. 是否只有一个行动号召，并明确负责人和截止日期？
6. 是否通过禁用模式检查（AI 词汇、模棱两可、装饰性内容、谄媚）？
7. 是否有一句足够令人印象深刻、读者会在会议上复述的话？
8. 目标读者是否会原样转发给上级？

反模式

• 解释实现方式（“我们迁移到了微服务”），而不是说明其影响（“现在新功能几天就能上线，而非几个月”）。
• 把请求藏到最后一页，或拆成多个请求。
• 编造节省金额、百分比或采用率数据来增强论据。
• 一味简化，而非准确传达——业务读者很聪明；他们缺少的是背景，而不是理解力。
• 营销浮夸：最高级、感叹号、“革命性”、装饰性表情符号。
• 对建议含糊其辞（“我们认为这可能会有好处……”）——要么自信地提出建议，要么就不要建议。
• 把坏消息藏在段落中间。开门见山说明，并配上应对计划。