name: writing-voice description: 所有书面内容的声音和音调规则。用于写作应该听起来人性化、适合朗读的散文。

写作声音

核心原则：为耳朵写作，不仅仅是眼睛。散文应该适合大声朗读。

测试

大声读出来。如果它：

听起来像新闻稿 → 重写
听起来像公司备忘录 → 重写
听起来生硬或不自然 → 重写
听起来像你在向同事解释 → 发布

AI 明显痕迹

显示出“AI写了这个”的模式：

到处加粗格式：在正文内容中从不加粗章节标题
把所有东西都变成项目列表：尽可能转换为流畅的段落
营销词汇：“游戏改变”、“革命性”、“释放”、“赋能”
结构化部分：“关键特性：”、“好处：”、“为什么这很重要：”
模糊的最高级：“极其强大”、“无缝集成”
戏剧性的夸张：“感觉像永恒”、“痛点”、“折磨人的” —— 使用事实代替
AI 形容词：“完美地”、“毫不费力地”、“美丽地”
空格-连字符-空格：“代码工作 - 测试通过”
过度使用片段：“每。次。” （一次是强调，两次是模式）
断奏式 buildup：设置。片段。片段。片段。 punchline。这种“戏剧性揭示”模式感觉是制造的。使用 em dash 或分号合并成一个流畅的句子。
强制特异性：没有意义的随机数字

标点符号

从不使用“ - ”（空格-连字符-空格）或“ — ”（空格-em-dash-空格）。更喜欢简单的标点：

更喜欢	当
句号 (.)	默认选择。两个句子通常比一个更清晰。
冒号 (:)	引入解释：“事情是这样的：它不工作”
分号 (;)	相关的独立从句：“代码工作；测试通过”
Em dash (—)	sparingly，用于打断或强调：“它快——真的快”

Em dash 可以用，但容易过度使用。当有疑问时，使用句号。

如何写好散文

前面的部分说了要避免什么。这部分说要做什么。

以要点开头

每个段落都应该以结论开头。设置之后，不是之前。读者应该知道你要去哪里，在你带他们去那里之前。

坏（埋没要点）：

在调查了几种冲突解决方法后，包括 CRDTs、操作转换和手动合并策略，我们发现 Yjs 与 LWW 时间戳给了我们正确性和简单性的最佳组合。

好（以它开头）：

Yjs 与 LWW 时间戳给了我们最佳的冲突解决。我们尝试了没有时间戳的 CRDTs、操作转换和手动合并策略；没有一个在这么少的代码中匹配它的正确性。

变化句子长度

单调的句子长度是听起来机器人最快的方式。混合短声明句与长解释句。短句有冲击力。长句承载细微差别并连接需要一起存在的想法。

坏（均匀长度）：

系统处理传入事件。它验证每个事件对模式。它然后将事件路由到适当的处理程序。处理程序相应地更新数据库。

好（变化节奏）：

系统验证传入事件对模式并将它们路由到正确的处理程序。简单足够。但处理程序必须更新数据库、通知订阅者并在单个事务中维护审计日志。这就是它变得有趣的地方。

使用具体语言

抽象语言迫使读者做翻译工作。具体语言让他们立即看到。

坏（抽象）：

这种方法为数据检索操作提供了显著的性能改进。

好（具体）：

行查找从 O(n) 降到 O(1)。在 10,000 行表上，那是扫描每个单元格与单个哈希查找的区别。

连接想法无需标题

不是每个过渡都需要章节标题。使用桥接句子：一段末尾的句子设置下一个主题，或开头链接回。标题打断读者的流程；使用它们用于重大转变，不是每个新想法。

坏（标题重）：

问题

会话超时。

根因

刷新只在导航上触发。

解决方案

我们添加了 keepalive 到后台活动。

好（流畅）：

会话在文件上传期间超时。刷新逻辑只在导航事件上触发，所以任何后台活动——上传、同步、长运行变异——会 silent 失去会话。

修复是 keepalive，在任何认证请求上触发，不仅仅是页面转换。

常见重写模式

无需判断的机械替换：

如果你写了…	重写为…
“重要的是要注意 X”	“X”
“为了达到 Y，我们需要 Z”	“Z 给我们 Y”
“这工作的原因是…”	“这工作因为…”
“这意味着…”	直接陈述它
“应该注意…”	完全删除它
“基本上，X”	“X”
“如前所述/如上”	只是重新陈述那件事
“这允许我们…”	“我们现在可以…” 或 “现在 X 工作”
“我们需要确保…”	“X 必须…” 或 just do it
“在…的上下文中”	删除它或具体化
“值得一提…”	提及它或不
“向前推进，我们将…”	“下一步：…” 或 just describe the action
“利用” / “使用”	“使用”
“促进”	“让”、“启用” 或 “允许”
“实施解决方案”	“修复它” / “构建它” / say what you built

解释技术概念

当解释某物如何工作时，展示机制，不是营销。以发生什么开头，然后为什么。

坏（过度解释，AI 声音）：

这里的关键洞察是通过利用 Yjs 的内置冲突解决机制，我们可以有效地处理并发编辑，以无缝维护所有连接客户端的一致性。

好（直接，展示机制）：

Yjs 自动解决冲突。两个用户编辑同一字段，两个编辑在 CRDT 中生存，LWW 时间戳选择赢家。不需要手动合并逻辑。

坏（抽象）：

工厂函数模式通过封装客户端创建逻辑并为消费者暴露定义良好的接口，提供了清晰的关注点分离。

好（具体）：

createSync() 取一个 Y.Doc 并返回三个方法：connect()、disconnect() 和 status()。消费者从不接触 WebSocket 设置、重连逻辑或 auth token 刷新。他们调用 connect() 并且它工作。

自然散文

像人类讲故事一样写作，不是新闻稿。
避免在标题和正式内容中使用表情符号，除非明确请求

开源和产品写作

当写作落地页或产品面向散文时：

以工具实际做什么开头，不是为什么它惊人
强调用户控制和数据所有权
突出透明度：审计代码，无跟踪，无中间人
呈现诚实的成本比较，具体、真实的数字
公开承认限制和权衡
使用诚实的比较语言：“我们相信 X 应该是 Y”
呈现事实并让用户得出结论

好与坏示例

好（自然，人类）：

“我每月支付 30 美元用于转录应用。然后我计算了：实际 API 调用成本约 0.36 美元/小时。在我的使用量（3-4 小时/天），我支付 30 美元 for what should cost 3 美元。

所以我构建了 Whispering 来切断中间人。你带自己的 API 密钥，你的音频直接去提供者，你支付实际成本。无订阅，无数据收集，无锁定。”

坏（AI 生成感觉）：

“介绍 Whispering - 一个革命性的转录解决方案，赋予用户前所未有的控制。

关键好处：

成本效益：节省高达 90% 的转录成本

隐私第一：你的数据从不离开你的控制

灵活：多个提供者选项可用

为什么 Whispering？ 我们相信转录应该对每个人可访问…”

区别：故事 vs 结构化部分，个人 vs 公司，具体数字 vs 模糊声称。

声音匹配

当用户提供示例文本或音调指导时，匹配它：

如果他们简洁，简洁
如果他们给 5 个句子，不写 5 个段落
如果他们使用直接陈述，不添加叙事修饰
匹配他们的能量，不是模板