Deno 文档编写风格指南

本指南概述了为 Deno 编写文档的标准和最佳实践。遵循这些指南有助于确保我们的文档保持一致、清晰，并且对所有用户都有帮助。

文档结构 Jump to heading#

Front Matter Jump to heading#

每个 Markdown 文件应以 front matter 开头，包含：

---
title: "描述性标题"
description: "页面内容的简要概述（1-2 句话），将显示在搜索结果和链接预览中。"
oldUrl:  # 可选 - 用于以前文档位置的重定向
- /previous/url/path/
---

标题：简洁且具有描述性，需用引号括起。

描述：1-2 句（140-160 字符）概述页面内容。

介绍段落 Jump to heading#

每篇文档开头应有简短介绍，说明：

• 功能/概念是什么
• 为什么有用
• 谁可能需要这部分信息

内容组织 Jump to heading#

内容应符合逻辑顺序：

1. 基础概念优先
2. 常见用例
3. 高级功能
4. 参考信息

写作风格 Jump to heading#

语气与风格 Jump to heading#

• 保持对话式但专业 — 以向同事解释的语气写作
• 使用主动语态 — 如 “Deno 提供…” ，而非 “…由 Deno 提供”
• 直截了当 — 文中直接称呼读者为 “你”
• 简洁明确 — 使用简单句，避免不必要的词语

技术写作惯例 Jump to heading#

• 在使用术语前先进行定义
• 整篇文档中术语保持一致
• 避免使用可能让非英语母语者困惑的成语和口语表达

语法与规范 Jump to heading#

• 使用美式英语拼写与惯例
• 尽量使用现在时态
• 正式说明中避免缩写（用 “cannot” 代替 “can't”）
• 标题使用句式大小写（仅首词和专有名词大写）

代码示例 Jump to heading#

格式 Jump to heading#

• 始终指定用于语法高亮的语言
• TypeScript/JavaScript 使用 ts 或 js 标识
• 适当时使用 title 属性包含文件名

```ts title="example.ts"
function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("world"));
```

示例最佳实践 Jump to heading#

• 示例保持简单，聚焦于展示单一概念
• 确保示例功能正确可运行
• 复杂或不易理解代码应添加注释
• 展示基本和实际用例
• 较长示例应逐步构建

文档测试 Jump to heading#

对于应测试的代码块：

• 确保文档示例正确且可运行
• 使用带语言标识的三重反引号启用可测试代码块
• 遵循文档测试中的指南

格式元素 Jump to heading#

链接 Jump to heading#

• 使用上下文中即可理解的描述性链接文本
• 内部链接使用相对路径，末尾加 /： /runtime/fundamentals/modules/
• 引入新概念时链接到相关文档

[描述性文本](/path/to/page/)

列表 Jump to heading#

• 顺序步骤用序号列表（1., 2., 3.）
• 非顺序项用无序列表（项目符号）
• 列表项结构保持一致
• 每项首词首字母大写

提示框（注释、提示、警告） Jump to heading#

慎用提示框强调重要信息：

:::note 重要补充信息。:::

:::info Informational content (styled like note). :::

:::tip Helpful advice for better usage. :::

:::caution Warn about potential issues or gotchas. :::

:::warning Critical warnings that require immediate attention. :::

表格 Jump to heading#

用于展示结构化数据：

| 表头 1 | 表头 2 |
| ------- | ------- |
| 单元格 1 | 单元格 2 |
| 单元格 3 | 单元格 4 |

特定内容类型 Jump to heading#

命令参考 Jump to heading#

CLI 命令文档应：

• 以清晰说明命令功能开头
• 列出所有可用参数和选项
• 包含常见用法示例
• 尽可能展示预期输出

API 文档 Jump to heading#

API 文档应：

• 清晰定义参数和返回值
• 指定所有参数类型
• 提供常用用例示例
• 记录可能的错误或异常

教程 Jump to heading#

教程类文档应：

• 以前提条件和学习目标开始
• 分解为明确的编号步骤
• 提供完整代码示例
• 解释每步背后的“原因”，不仅是“如何做”
• 结尾给出后续步骤或相关资源

视觉元素 Jump to heading#

截图和图片 Jump to heading#

• 所有图片应包含替代文本
• 保持图片与当前界面一致
• 裁剪图片突出相关部分
• 使用标注突出重点区域
• 确保图片在不同屏幕尺寸下清晰

图表 Jump to heading#

• 用图表解释复杂概念或流程
• 保持图表简洁，聚焦关键信息
• 配合图表提供文本说明

包容性用语 Jump to heading#

• 使用性别中性语言
• 避免使用有历史负面含义的术语
• 注意全球受众，避免文化专属引用
• 遵循 包容性代码指南

审核流程 Jump to heading#

提交文档前：

1. 验证技术准确性
2. 检查内容清晰易读
3. 确保格式统一
4. 校验所有链接
5. 测试所有代码示例
6. 检查拼写和语法错误

文件组织 Jump to heading#

• 新文件应放置于对应内容类型的目录
• 文件名使用小写，单词间用下划线分隔（如 setup_environment.md）
• 添加新页面时遵循现有导航结构