Back to Details

business-storyteller

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Business storyteller

商业叙事工具

Turn technical work into documents that non-technical colleagues read, understand, and approve. The craft is translation plus persuasion: start from the business outcome and work backwards to the technology, prove every claim with a real number, and tell it as a story the reader can repeat in their next meeting. Professional and rich, never banal; persuasive, never manipulative.
将技术工作转化为非技术同事愿意阅读、理解并认可的文档。核心是翻译加说服：从业务成果倒推技术，用真实数据佐证每一项主张，讲述一个读者能在下次会议中复述的故事。文档需专业详实，绝不平庸；有说服力，但绝不操控。

When to use

使用场景

  • Presenting a feature, product, or release to the whole company
  • Writing an approval proposal for a feature, refactor, migration, or technical investment
  • Explaining a fix or incident to management, compliance, or customer-facing teams
  • Explaining how the software works to admin, sales, marketing, HR, finance, or accounting
  • Turning any technical artifact (spec, PR, changelog, postmortem) into business communication
  • 向全公司展示功能、产品或版本发布
  • 为功能开发、重构、迁移或技术投资撰写审批提案
  • 向管理层、合规团队或客户-facing团队解释问题修复或事件
  • 向行政、销售、营销、HR、财务或会计团队解释软件工作原理
  • 将任何技术制品（规格文档、PR、changelog、事后复盘报告）转化为商业沟通材料

Hard rules

硬性规则

  1. Relevance, not simplification. The reader does not need to understand how the system works — they need to know what changes for the company: money earned or saved, risk removed, time freed, capability unlocked. Start from that impact and work backwards; mention technology only when it earns its place.
  2. Outcome before capability. "Reports now load in 2 seconds instead of 40" — never "we optimized the database queries". Every technical fact gets translated through the table in the persuasion playbook.
  3. True numbers only. Concrete numbers persuade ("87% of users" beats "most users") — but only numbers the source provides. Never invent metrics, savings estimates, percentages, or deadlines. The rule also covers small "harmless" details writers add for texture: a meeting length, a sprint duration, a "30-minute" anything — if the source does not state it, it does not exist. Simple arithmetic on source numbers is fine (400 invoices × 15 min = 100 h/month), but anchor derived time spans to the right endpoints (time-from-detection is not time-from-first-failure). Before delivering, point every number in the draft back to a source fact; a number with no source gets cut or replaced with a qualitative claim. A document that wins approval on invented numbers loses trust forever. If a number would help and does not exist, ask the user for it.
  4. One ask per document. End with exactly one clear call to action: the decision needed, who decides, and by when. Two asks compete; three asks lose.
  5. Write in the language of the request. Portuguese request → Portuguese document. English request → English document. The same persuasion and banned-pattern rules apply in every language.
  6. Persuade, never manipulate. Loss framing, social proof, and urgency are allowed only when factually true. No false scarcity, no invented testimonials, no inflated risk. Front-load bad news — readers forgive problems, not surprises.
  1. 相关性优先，而非简化。 读者无需理解系统如何运作——他们需要知道公司会发生什么变化：赚了或省了多少钱、消除了哪些风险、节省了多少时间、解锁了哪些能力。从影响入手倒推；仅当技术内容能体现价值时才提及。
  2. 先讲成果，再讲能力。 要写“报表加载时间从40秒缩短至2秒”——而非“我们优化了数据库查询”。每一项技术事实都需通过说服手册中的对应规则转化为业务价值。
  3. 仅用真实数据。 具体数据更具说服力（“87%的用户”优于“大多数用户”）——但必须是来源提供的数据。绝不能编造指标、节省估算、百分比或截止日期。这条规则也适用于作者为丰富内容添加的小细节：会议时长、迭代周期、“30分钟”之类的描述——如果来源未提及，就不能写。基于来源数据的简单计算是允许的（400张发票×15分钟=每月100小时），但衍生的时间跨度需锚定正确的端点（检测耗时不等于首次故障后的耗时）。交付前，需将草稿中的每一个数据追溯到来源事实；无来源的数据需删除或替换为定性描述。靠编造数据获得批准的文档会永远失去信任。如果某个数据对文档有帮助但不存在，请向用户索要。
  4. 每份文档仅含一个诉求。 结尾需明确给出一个行动号召：所需做出的决策、决策者以及截止时间。两个诉求会相互竞争；三个诉求则会无人理会。
  5. 按请求语言撰写。 葡萄牙语请求→葡萄牙语文档；英语请求→英语文档。所有说服规则和禁用模式适用于所有语言。
  6. 说服而非操控。 仅当事实确凿时，才可使用损失框架、社会认同和紧迫感等技巧。禁止虚假稀缺、编造 testimonial、夸大风险。坏消息要放在前面——读者会原谅问题，但不会原谅隐瞒。

Process

流程

  1. Name the audience and the decision. Who reads this (a department, the leadership, the whole company)? What should they think, feel, or approve after reading? Weigh the message with the CRG model: finance reads cost, operations reads risk, leadership reads growth — same facts, different lead.
  2. Gather the source facts. Read the spec, PR, changelog, metrics, or conversation. List the facts and real numbers available. These are the only raw materials.
  3. Pick the document type and load both references. Read references/persuasion-playbook.md for the techniques and references/document-templates.md for the matching skeleton: feature announcement, approval proposal, fix/incident explainer, technical-debt case, how-it-works explainer, executive one-pager, or investor/strategic-partner product memo.
  4. Translate. Run every technical fact through capability → outcome. Replace each jargon term with its business meaning or cut it. If a term must stay (compliance, audit), define it in one plain sentence on first use. Jargon includes the words engineers stop noticing: module, refactor, sprint, deploy, rollback, staging, pipeline, environment, dependency, endpoint, backend, schema, migration, API, latency, p95 (módulo, refatoração, sprint, implantação, migração). The test: would a person in HR or accounting know this word from their own job? If not, translate it ("the billing module" → "the part of the system that calculates invoices"; "sprint time" → "the team's working time") or define it in passing. Translate the term, not into a guess: "sprint" does not become "two weeks" unless the source states the sprint length.
  5. Draft answer-first. The first sentence carries the conclusion: what this is and why the reader should care. Then the story, then the proof, then the ask. No throat-clearing, no "this document describes".
  6. Persuasion pass. Apply the playbook: quantified cost of inaction, the reader as hero of the story, concrete numbers, one memorable phrase the reader will repeat, confident language without hedging.
  7. Humanize pass. Remove every banned pattern (playbook list). Vary sentence rhythm. The document must read like a sharp colleague wrote it, not a machine or a press release.
  8. Produce the output. Markdown is the canonical deliverable. For PDF or HTML, follow the Output pipeline below.
  9. Self-check (bottom of this file) before delivering.
  1. 明确受众与决策目标。 谁会阅读这份文档（某个部门、领导层、全公司）？阅读后他们应形成什么看法、感受或做出什么批准？用CRG模型权衡信息：财务关注成本、运营关注风险、领导层关注增长——事实相同，侧重点不同。
  2. 收集来源事实。 阅读规格文档、PR、changelog、指标数据或对话记录。列出可用的事实和真实数据。这些是唯一的素材。
  3. 选择文档类型并参考对应模板。 阅读references/persuasion-playbook.md获取说服技巧，阅读references/document-templates.md获取匹配的文档框架：功能公告、审批提案、问题/事件说明、技术债务案例、工作原理说明、高管单页文档，或投资者/战略合作伙伴产品备忘录。
  4. 转译内容。 将每一项技术事实从能力转化为成果。用业务含义替换专业术语，或删除不必要的术语。如果术语必须保留（如合规、审计），首次出现时用一句平实的话定义。专业术语包括工程师习以为常的词汇：module、refactor、sprint、deploy、rollback、staging、pipeline、environment、dependency、endpoint、backend、schema、migration、API、latency、p95（葡萄牙语对应：módulo、refatoração、sprint、implantação、migração）。测试标准：HR或会计人员能从自身工作中理解这个词吗？如果不能，就转译（“账单module”→“系统中计算发票的模块”；“sprint时间”→“团队的工作周期”）或顺便定义。转译术语时不要猜测：“sprint”不能直接翻译成“两周”，除非来源明确说明迭代时长。
  5. 结论先行撰写草稿。 第一句话就要给出结论：文档主题以及读者为何要关心。然后讲述故事，提供证据，最后提出诉求。不要铺垫，不要写“本文档描述了……”。
  6. 优化说服性。 应用手册技巧：量化不作为的成本、将读者塑造成故事中的主角、使用具体数据、打造一句读者会复述的难忘短语、用自信的语言而非含糊的表述。
  7. 优化人文感。 删除所有禁用模式（手册列表中的内容）。变换句子节奏。文档读起来应像是一位敏锐的同事写的，而非机器或新闻稿。
  8. 生成输出。 Markdown是标准交付格式。如需PDF或HTML，请遵循下方的输出流程。
  9. 交付前进行自我检查（本文档底部）。

Output pipeline

输出流程

Markdown first, always — it is the reviewable source of truth.
Charts (only when data exists in the source): generate self-contained SVG with the bundled script (bootstrap helper — it creates files, modifies nothing else). Run it from the skill directory:
sh
python3 scripts/make_chart.py --type bar --title "Hours saved per week" \
  --data "Support:14,Finance:9,Operations:6" --out chart-hours.svg
Types: 
bar
, 
line
, 
donut
. Data values must come from the source — a chart of invented numbers is fabrication with extra polish.
HTML: copy templates/document.html, replace the 
{{...}}
placeholders, and write each section as simple HTML (
<h2>
, 
<p>
, 
<ul>
, 
<table>
, 
<blockquote>
). Inline any SVG charts inside 
<figure>
blocks. The template is self-contained (no CDN, no network) and print-ready.
PDF: render the HTML with the bundled export script (mutating helper — it writes the PDF file). It finds Chrome/Chromium automatically and reports the page count:
sh
sh scripts/export_pdf.sh document.html document.pdf
始终优先生成Markdown——它是可审核的事实来源。
图表（仅当来源存在数据时）：使用捆绑脚本生成独立SVG（引导工具——仅创建文件，不修改其他内容）。从技能目录运行：
sh
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
sh scripts/export_pdf.sh document.html document.pdf

OK: document.pdf (pages: 1)

OK: document.pdf (pages: 1)


If no Chrome/Chromium is installed, deliver the HTML and tell the user it prints to PDF from any browser (File → Print → Save as PDF).

**One-pager page limit.** The executive one-pager must fit a single A4 page. Use the template's compact mode (`<body class="compact">`) and check the `pages:` count the export script prints. If it still exceeds one page, do NOT cut content on your own — every section was built from facts the user cares about. List the candidate cuts (with what each would lose) and ask the user to decide what to cut, or whether a second page is acceptable. The user decides; you propose.

如果未安装Chrome/Chromium，交付HTML并告知用户可从任何浏览器打印为PDF（文件→打印→另存为PDF）。

**单页文档页数限制**。高管单页文档必须能容纳在一张A4纸内。使用模板的紧凑模式（`<body class="compact">`）并检查导出脚本显示的`pages:`计数。如果仍超过一页，请勿自行删减内容——每个章节都是基于用户关心的事实构建的。列出可删减的候选内容（以及删减会损失的信息），请用户决定删减哪些内容，或是否允许第二页。由用户做决定，你仅提供建议。

Self-check

自我检查

Every answer must be yes before delivering:
  1. Does the first sentence state the conclusion and why this reader should care?
  2. Could a person from HR or accounting read the whole document without stumbling on one unexplained technical term?
  3. Is every number real — present in the source or confirmed by the user?
  4. Is the cost of doing nothing stated (when the document asks for a decision)?
  5. Is there exactly one call to action, with owner and deadline?
  6. Does it pass the banned-patterns scan (AI vocabulary, hedging, decoration, sycophancy)?
  7. Is there one phrase memorable enough that a reader would repeat it in a meeting?
  8. Would the target reader forward this to their boss as-is?
交付前需确保以下所有问题的答案都是“是”：
  1. 第一句话是否说明了结论以及读者为何要关心？
  2. HR或会计人员能否通读整篇文档而不会遇到未解释的技术术语？
  3. 所有数据是否都是真实的——来自来源或经用户确认？
  4. 当文档请求决策时，是否说明了不作为的成本？
  5. 是否仅有一个明确的行动号召，包含负责人和截止时间？
  6. 是否通过了禁用模式扫描（AI词汇、含糊表述、装饰性内容、奉承话）？
  7. 是否有一句足够难忘的短语，读者会在会议中复述？
  8. 目标读者是否会直接将这份文档转发给他们的上司？

Anti-patterns

反模式

  • Explaining the implementation ("we migrated to microservices") instead of the consequence ("new features now ship in days, not months").
  • Burying the ask on the last page or splitting it into several requests.
  • Inventing savings, percentages, or adoption numbers to strengthen the case.
  • Dumbing down instead of translating — business readers are smart; they lack context, not intelligence.
  • Marketing fluff: superlatives, exclamation points, "revolutionary", emoji decoration.
  • Hedging the recommendation ("we believe it might be beneficial...") — recommend with confidence or do not recommend.
  • Hiding bad news in the middle of a paragraph. Lead with it and pair it with the plan.
  • 解释实现细节（“我们迁移到了microservices”）而非结果（“新功能现在只需几天即可上线，而非数月”）。
  • 将诉求放在最后一页或拆分为多个请求。
  • 编造节省金额、百分比或采用率来强化案例。
  • 简化内容而非转译——业务读者很聪明；他们缺乏的是背景知识，而非智力。
  • 营销 fluff：最高级、感叹号、“革命性的”、表情符号装饰。
  • 含糊的建议（“我们认为这可能有益……”）——要么自信地推荐，要么不推荐。
  • 将坏消息隐藏在段落中间。要放在前面并附上解决方案。