tech-docs-guide

什么时候使用

• 创建新的技术指南文档
• 编辑现有文档使其符合写作规范
• 审校文档格式和结构

执行流程

• Step 1: 严格遵循基本要求、文档结构要求、内容结构以及示例要求
• Step 2: 完成初稿后进行自我审校
• Step 2.1: 通过 web fetch 最新的相关信息验证内容准确性和时效性
• Step 2.2: 检查内容是否遵循写作规范
• Step 2.3: 检查内容逻辑是否清晰，是否易于理解
• Step 3: 根据审校建议修改内容，然后执行 Step 2 重新审校，直到审校问题修复
• Step 4: 执行格式化脚本：npm run format

基本要求

• 使用简体中文编写
• 代码示例简洁，聚焦核心概念
• 使用清晰的标题和子标题组织内容
• 包含实际应用场景的实用示例

文档结构

标题命名

使用「主题 + 完全指南/使用指南」格式：

# Git Hooks 完全指南

# TypeScript 使用指南

章节编号

层级	格式	示例
一级章节	数字编号	## 1. 概述
二级章节	点号分隔	### 1.1 什么是 XX
三级章节	点号分隔	#### 1.1.1 详细说明

结尾部分

• 总结章节：回顾核心要点，可包含速查表
• 参考资源章节：提供官方文档和相关资源链接

不使用的元素

• 不使用目录
• 不使用章节分隔线（---）

内容格式

表格

大量使用 markdown 表格进行对比说明、参数说明、速查总结。

图解

• 简单图解：优先使用 ASCII 艺术（Git 分支图、流程图）
• 复杂图形：使用 Mermaid 语法（类图、时序图、流程图）

代码块

// ✅ 好的实践：简洁、有中文注释
function greet(name) {
  return `Hello, ${name}`;
}

// ❌ 坏的实践：冗长、无注释

要点：

• 标注语言类型（bash, json, javascript 等）
  • 如果需要支持 json 注释，使用 jsonc
• 只包含必要的关键代码
• 使用中文注释说明关键步骤
• 使用 // ✅ 和 // ❌ 标记好/坏实践

嵌套代码块

当需要在文档中展示包含代码块的 Markdown 示例时，外层使用 4 个反引号，内层使用 3 个反引号：

````markdown
## 示例标题

```bash
python scripts/example.py
```
````

注意：嵌套代码块的开头和结尾反引号数量必须一致，否则会导致渲染错误。

提示信息

使用引用块格式：

> **注意**：重要警告或注意事项

> **提示**：有用的建议

> 说明：补充说明信息

对比说明

使用 ✅ 和 ❌ 标记好/坏实践，可在正文或代码注释中使用。

FAQ（可选，QA可以加深技术理解）

**Q1: 问题内容？**

解答段落或代码示例...

问题聚焦于技术实现、常见错误排查、配置疑难等技术内容（和当前的技术主题相关联）。

速查表

在总结章节提供表格形式的快速参考。

示例规范

• 提供完整可运行的代码示例
• 包含多个实际应用场景（场景1、场景2...）
• 代码示例中使用中文注释说明关键步骤
• 复杂操作提供分步骤说明（1. 2. 3.）