写作散文
这些规则适用于任何语言的 Markdown 文档和代码注释。标有“仅限 Markdown”的规则不适用于代码注释。在这些区域，代码注释遵循其语言的惯例，例如 Go 的 [Name] 文档链接。针对特定文档类型（如 ADR 和词汇表）的技能会在这些规则之上添加自己的规则。
语调
轻松但精确。以一位经验丰富的工程师向另一位工程师解释主题的方式写作。避免过度正式的规范语言。优先选择清晰、自然的解释，同时保持技术准确性。语气应平易近人、具有对话性，但不要随意。
假设读者具备中级软件开发水平，但可能不了解 Dogmatiq 项目或文档所属领域。避免使用行话，并解释文档中需要的任何技术术语。将读者设想为一位拥有约五年专业经验、熟悉 Go 但在算法或数学方面背景较浅的应用开发人员。
文件名（仅限 Markdown）
使用小写文件名，例如 glossary.md，除非外部约定另有要求，例如 LICENSE 或 README.md。
换行（仅限 Markdown）
重新排列每个段落，使每行在 80 个字符内容纳尽可能多的单词。
标点符号
- 在散文中使用直引号和直撇号（
",'），绝不使用弯引号。非 ASCII 字符在代码块和公式中是可以的。 - 书写 em dash 时两侧各加一个空格，例如
word — word。 - 作为括号分隔符时使用 em dash，而不是连字符。
- 在列表和段落中，使用 em dash 表示定义术语的同位语。不要使用冒号、分号或括号来执行此操作。
- 考虑重构包含大量 em dash 的句子或段落。
- 少用分号，用于对比（A；B 不）、限定（A；然而 B）或逻辑结果（A；因此 B）。如果从句自然地读作两个独立的句子，则优先使用句号。
- 将散文中的双连字符（
--）替换为适当的 em dash。否则，建议使用正确的标点。
拼写
使用美式英语。如有疑问，请遵循 go.dev、Go 标准库文档或 AWS 和 GCP 文档。
| 美式（正确） | 非美式（错误） |
|---|---|
| analyze | analyse |
| behavior | behaviour |
| canceled | cancelled |
| center | centre |
| color | colour |
| initialize | initialise |
| labeled | labelled |
| serialize | serialise |
参考链接（仅限 Markdown）
- 使用引用式链接，绝不使用内联链接。
- 将链接定义放在文件底部，按组排列，每组以标签 HTML 注释开头，例如
<!-- references -->或<!-- anchors -->。 - 每组按标签字母顺序排序。例外情况是
CHANGELOG.md中的版本链接，它们保持升序版本顺序，因此[0.9.0]在[0.10.0]之前。 - 当链接术语以复数形式出现时，为复数形式添加单独的定义，例如
[instructions]: #instruction，以便源文本读起来自然。 - 每个定义必须至少使用一次。删除未使用的定义。
- 每个引用必须有匹配的定义。不要留下无效引用。
审阅
对照以上每条规则检查文本。对于每个问题，引用文本，指出其违反的规则，并建议修正。