文档风格指南 | EmDash CMS Everything

本指南定义了 EmDash 文档的编写方式。贡献内容会被编辑以符合本指南。你不需要背诵它——审查者和编辑会帮忙——但遵循它可以加快贡献的合并。

文档的存在是为了帮助某人完成某事，然后回到他们的项目中。为疲惫的、赶时间的、使用第二语言阅读的或刚接触技术栈的读者而写。首先服务于这位读者。

可读性

优先选择：

短句和短段落。
简明词汇而非术语。
缩写和首字母缩写词第一次出现时写全称。
使用标题和列表分割长段落。
主动语态。

文档化如何使用 EmDash 构建，而不是EmDash 是如何构建的。实现细节仅在它改变读者必须做出的决策时才属于文档（何时选择非默认值、影响其项目的注意事项）。它永远不会替代使用示例。

对于非 EmDash 主题——TypeScript、AT Protocol、Web 字体、SQL——链接到可靠的来源而不是解释它们。文档化某人在 EmDash 中使用该功能需要知道的内容。

应该强调什么

页面的重点必须由读者完成任务所需的内容来决定，而不是由构建 EmDash 的人觉得有趣或最近才做的事情来决定。需要积极抵制的三个习惯：

写作新鲜感权重。 一个决定是新的，或者在作者脑海中还很新鲜，这不是突出它的理由。最常更改的东西对读者来说很少是最重要的。按读者需要的频率而不是添加的时间来排列章节、列表项和标题。如果你因为某些东西刚刚更改而文档化它，你可能在写变更日志条目，而不是文档。
构建者相关性高于读者相关性。 对于做出来说重要的内部架构和设计决策，通常对于使用来说是不可见和无关的。说明读者获得的能力，而不是其背后的机制。定义集合的读者不需要知道模式存储在哪里，就像他们不需要知道解析器的语言一样。如果机制确实帮助了在 EmDash 上工作的人，它属于内部文档，而不是面向用户的页面。
稻草人式自我定义。 不要通过与其他工具的漫画形象对比来定义 EmDash（“与大多数 CMS 不同……”、“传统 CMS 迫使你……”、“在许多 CMS 中你在代码中声明 X”）。直接描述 EmDash 做什么，让它自己站稳。比较仅在比较是读者自己的问题时才被允许：在评估页面和”来自……”定向页面上。即使在那里也必须具体且公平——具体的行为和权衡，而不是邀请读者不喜欢的稻草人。
通过否定来定义。 将能力框架为你_不必_做的工作——“不需要编写迁移”、“不需要重建”、“不需要碰代码”、“不需要单独的服务”——是伪装的稻草人：它只对携带你为他们发明的替代方案的读者有效。说明读者_做什么_以及_发生什么_。“在管理面板中添加字段；立即生效”——而不是”添加字段无需迁移、无需重建、无需代码”。例外是以积极方式表述的具体、与读者相关的行为：“内容在运行时提供，因此编辑立即显示”是关于 EmDash 的事实；“不需要重建”是以别人不存在的痛苦来表述的同一事实——优先选择前者。

任何句子的测试：如果删除它，试图完成任务的读者是否会更糟？如果不会，删除它。如果它只对将 EmDash 与其他东西比较的读者有意义，那么它在错误的地方或应该被删除。

常青，而非变更日志

面向用户的页面描述 EmDash 现在如何工作，面向脑海中没有任何先前版本的读者。没有”现在”、“不再”、“以前”、“代替旧的”、“这已更改”。版本间差异仅存在于升级指南中。概念最近被引入永远不是提及它是最近的理由。

声音和语调

写中立、事实性的句子。直接陈述事实。

✅ 插件在隔离的运行时中运行，只能访问它们声明的 API。

❌ 插件住在一个温馨的小沙箱里，坏事永远不会发生！

不要使用_我们_、我们的_或_让我们。 你不是和读者坐在一起。改写为直接称呼读者或描述系统。
永远不要使用_我_。 文档不是关于作者的。
需要时称呼读者为_你_，特别是标记可能出问题的步骤时。
不要叙述或讲故事。 没有”既然我们已经设置了 X，让我们继续 Y”。用目标开始一个部分，然后是步骤。
避免奇思妙想、吉祥物和文化引用。 它们增加阅读负担且无法翻译。
感叹号很少使用。 仅用于真正令人鼓舞或惊讶的事情。不确定时用句号。

标题

页面标题是 <h1>（来自 frontmatter title）。章节从 <h2> 开始。
保持标题简短。<h2> 和 <h3> 出现在”本页内容”侧边栏中；预览并缩短任何换行的内容。
不要有尾随标点，包括冒号。
标题中的代码格式使用 <code>，与正文中相同。

列表

当顺序不重要时使用无序列表，如一组选项或属性。
对必须按顺序执行的步骤使用有序列表。对于流程使用 Starlight 的 <Steps> 组件。
当列表项增长为多个段落或包含多个代码术语时，改用 <h3> 章节。

示例

“例如”完整形式引入单个示例或假设。
括号内的”如”引入非穷举列表（如 GitHub、GitLab）。
涵盖每个选项的列表不是示例列表——使用不带”如”的括号（必需属性 (src, alt)）。

截图

仅当截图实质性地澄清空间关系、界面状态或控件位置时才使用。将说明和其他重要信息保留在文本中，以便页面在没有图片的情况下仍然可用。

每个截图必须是最新的，并为页面的特定目的而捕获。提供描述相关屏幕和状态的替代文本。记录 fixture、路由、视口、区域设置和主题，以便其他贡献者可以重现捕获。

代码示例

代码示例与周围的文字一样重要。

用一个完整的、独立的句子在自己的行上引入每个代码块，告诉读者该块做什么。不要以冒号结尾的句子片段、裸标题或”如下：“来引入。

✅ 以下示例在 sandboxed 数组中注册一个插件：

❌ 像这样添加插件：

引入让读者准备好代码_做什么_，这样他们只需要弄清楚_如何_。它还为做稍微不同的事情的读者创建了一个填空模式。

在 <Steps> 流程中，直接的祈使句指令就是引入（“添加 tsconfig.json`：” 后跟文件在编号步骤中是可以的）。

其他规则：

使用真实、可运行的代码。 没有 foo/bar。展示一个现实的配置，而不是每个可能的值——读者只会有一个。
对任何代表文件的代码块添加 title= 文件名，以便读者知道代码放在哪里。
```
```ts title="src/plugin.ts"
```
对前后更改使用 Expressive Code 注解，而不是原始的 ```diff 围栏。用 del={n} / ins={n} 标记更改的行，或用 del="…" / ins="…" 标记更改的文本。保持 diff 最小化且仅限于更改的行。

以下示例展示了单行更改：
```
```ts del={1} ins={2}
import { definePlugin } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";
```
```
提交前在本地预览渲染的代码。一个拼写错误可能破坏显示。

升级和迁移指南

帮助读者将现有项目迁移到新版本的指南遵循固定结构。“我应该做什么？“部分是读者最重视的部分——不要吝啬。

以以下内容开始：如何升级，事情可能”直接工作”但如果不行就继续阅读的说明，以及变更日志的链接。

然后将每个破坏性更改列为自己的条目：

### [重命名/更改/删除/弃用]：<功能>

在早期版本中，<一句话，过去时态，做了什么>。

<一句话，现在时态，现在如何工作>。

#### 我应该做什么？

<祈使动作：更新… / 替换… / 删除…，带最小差异。>

根据读者感受影响的方式选择动词。如果新的默认值替换了他们的值，那是”更改：默认值”，而不是”添加：选项”。

破坏性更改是需要更改读者项目否则就停止工作的更改。给出操作，而不仅仅是事实。不是”Node.js 的最低版本现在是 X”，而是”使用以下命令检查你的 Node.js 版本，如果低于 X 则升级”。

EmDash 特定事项

针对反复出现的情况的规范，按贡献者遇到的频率排序。这是一份规范列表，不是哪些功能更重要的排名。

插件：沙箱 vs 原生

沙箱和原生插件是具有不同编写形式的不同格式。对一个的更改很少影响另一个。说明页面或示例涉及哪种格式。编辑沙箱插件页面时，不要更改原生插件示例，反之亦然。

本地化

不要在文档 PR 中包含 messages.po 更改。一个工作流在合并到 main 时提取目录。包含它们会造成无谓的变动和合并冲突。

实验性功能

实验性标志后面的功能，或 RFC 下的不稳定线协议格式，可能会在没有通知的情况下更改。保持其文档简洁，用注意 <Aside> 标记，并指向 RFC 或讨论作为真实来源。不要详尽地文档化不稳定的接口。

Atmosphere 账户

当 Bluesky 和更广泛的 AT Protocol 网络背后的可移植的、用户拥有的身份出现时，称之为 Atmosphere 账户并一致使用该术语。将第一次提及链接到 Atmosphere 登录指南或 atmosphereaccount.com。did:plc:… 和句柄是其具体标识符；在需要字面值的地方使用它们。

文档就是代码

文档站点是一个与 EmDash 相邻的 Astro 项目。文档更改经历与代码相同的拉取请求和审查流程。每个文本更改都等待审查；措辞更改可能会改变句子的含义或需要在站点其他地方进行匹配的编辑。小的、经过审查的、一致的更改保持整个站点的连贯性。