文档风格指南 | EmDash CMS Everything

本指南定义了 EmDash 文档的编写方式。贡献内容将被编辑以符合本指南。你不需要记住它——审阅者和编辑会提供帮助——但遵循它会让贡献更快地被合并。

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

可读性

优先选择：

短句和短段落。
简单的词汇而非术语。
缩写和首字母缩略词第一次使用时写全。
标题和列表来分隔长段落。
主动语态。

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

对于非 EmDash 主题——TypeScript、AT 协议、网页字体、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））。

代码示例

代码示例与围绕它们的文字一样重要。

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

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

❌ 像这样添加插件：

引言为读者准备代码做什么，所以他们只需要弄清楚_如何_。它还为做略有不同事情的读者创建了一个填空模式。

在 <Steps> 过程中，直接命令式指令是引言（在编号步骤中，“添加 tsconfig.json：“后跟文件是可以的）。

其他规则：

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

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

升级和迁移指南

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

以以下内容开始：如何升级，事情可能”正常工作”但如果没有请继续阅读的说明，以及指向变更日志的链接。

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

### [Renamed/Changed/Removed/Deprecated]: <feature>

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

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

#### 我该怎么做？

<命令式操作：更新… / 替换… / 删除…，使用最小的差异。>

根据读者如何感受影响来选择动词。如果新的默认值替换了他们的值，那就是”Changed: default value”，而不是”Added: option”。

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

EmDash 特定内容

针对反复出现的情况的约定，按贡献者遇到它们的频率排序。这是一个约定列表，不是哪些功能重要的排名。

插件：沙盒化 vs 原生

沙盒化插件和原生插件是具有不同创作形式的不同格式。对其中一个的更改很少影响另一个。说明页面或示例是关于哪种格式的。编辑沙盒化插件页面时，不要更改原生插件示例，反之亦然。

本地化

不要在文档 PR 中包含 messages.po 更改。工作流在合并到 main 时提取目录。包含它们会造成混乱和合并冲突。

实验性功能

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

Atmosphere 账户

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

文档是代码

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