内容规范

写作风格

1.1 语言风格

1.1.1 简洁明了

• 使用简单直接的语言
• 避免冗余和重复
• 每个句子表达一个观点

1.1.2 客观中立

• 使用第三人称视角
• 避免主观评价
• 基于事实和数据说话

1.1.3 专业规范

• 使用标准术语
• 保持术语一致性
• 首次出现的缩写需注明全称

1.2 语气要求

1.2.1 正式程度

技术文档应保持适度正式，避免过于随意的表达。

推荐：

• "用户需要配置环境变量"
• "系统将返回错误代码"

避免：

• "你得先把环境变量搞定" ❌
• "系统会报错" ❌

1.2.2 主动语态

优先使用主动语态，使句子更直接有力。

推荐：

• "开发者应遵循以下步骤"

避免：

• "以下步骤应被开发者遵循" ❌

段落组织

2.1 段落结构

2.1.1 段落长度

• 每段控制在 3-5 句
• 复杂概念可适当延长
• 避免超过 7 句的长段落

2.1.2 段落开头

每段的第一句应概括该段主要内容。

2.1.3 逻辑连接

段落间使用适当的过渡词保持连贯：

• 因果关系：因此、所以、由于
• 转折关系：但是、然而、不过
• 递进关系：此外、而且、同时
• 总结关系：总之、综上所述

2.2 列表使用

2.2.1 无序列表

用于并列关系的内容：

• 各项之间无先后顺序
• 各项重要性相同
• 可任意调换顺序

2.2.2 有序列表

用于有顺序要求的内容：

1. 操作步骤
2. 优先级排序
3. 时间顺序

2.2.3 列表规范

• 列表项保持语法结构一致
• 列表项首字母统一大小写
• 短列表项末尾不加标点
• 完整句子末尾加句号

代码示例

3.1 代码块规范

3.1.1 语言标识

代码块必须指定语言类型：

```javascript
const example = "Hello World";
```

3.1.2 代码注释

关键代码需添加注释说明：

// 初始化配置对象
const config = {
  port: 3000,      // 服务端口
  host: 'localhost' // 服务地址
};

3.1.3 代码长度

• 示例代码控制在 50 行以内
• 超长代码提供完整版链接
• 可用省略号表示省略部分

3.2 代码质量

3.2.1 可运行性

示例代码应该是可运行的完整代码。

3.2.2 最佳实践

代码示例应展示推荐的编码方式。

3.2.3 错误示例

提供错误示例时需明确标注：

// ❌ 错误示例
var x = 1;

// ✅ 正确示例  
const x = 1;

图表规范

4.1 图片使用

4.1.1 图片格式

• 截图：PNG 格式
• 图表：SVG 优先
• 照片：JPEG 格式

4.1.2 图片命名

遵循文件命名规范，使用描述性名称：

• architecture-diagram.png
• user-flow-chart.svg

4.1.3 图片说明

每张图片需要配备说明文字：

![系统架构图](./images/architecture.png)
*图 1: 微服务架构示意图*

4.2 表格规范

4.2.1 表格对齐

• 文本左对齐
• 数字右对齐
• 标题居中

4.2.2 表格示例

参数名	类型	必填	说明
name	string	是	用户名称
age	number	否	用户年龄
email	string	是	邮箱地址

4.2.3 表格大小

• 列数不超过 6 列
• 超宽表格考虑拆分
• 复杂数据考虑其他展示方式

引用规范

5.1 引用格式

5.1.1 行内引用

短引用使用行内代码格式：package.json

5.1.2 块引用

长引用或重要提示使用引用块：

注意： 这是一个重要提示。

请确保在生产环境中遵循此规范。

5.1.3 引用来源

引用外部资源需注明来源：

"Talk is cheap. Show me the code."

—— Linus Torvalds

5.2 链接规范

5.2.1 内部链接

使用相对路径链接项目内文档：

[文档结构规范](./structure.md)
[返回首页](../index.md)

5.2.2 外部链接

外部链接需在新标签页打开：

[MDN Web Docs](https://developer.mozilla.org/)

5.2.3 锚点链接

页内跳转使用锚点：

[跳转到第一节](#第一节-写作风格)