tech-docs-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

什么时候使用

When to Use

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

Create new technical guide documents
Edit existing documents to comply with writing standards
Review document format and structure

执行流程

Implementation Process

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

Step 1: Strictly follow basic requirements, document structure requirements, content structure, and example requirements
Step 2: Self-review after completing the first draft
Step 2.1: Verify content accuracy and timeliness by fetching the latest relevant information via web
Step 2.2: Check if content complies with writing standards
Step 2.3: Check if content logic is clear and easy to understand
Step 3: Revise content based on review suggestions, then re-execute
```
Step 2
```
for review until all issues are resolved
Step 4: Run the formatting script:
```
npm run format
```

基本要求

Basic Requirements

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

Write in Simplified Chinese
Keep code examples concise, focusing on core concepts
Organize content with clear headings and subheadings
Include practical examples of real-world application scenarios

文档结构

Document Structure

标题命名

Title Naming

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

markdown

undefined

Use the format "Topic + Complete Guide/Usage Guide":

markdown

undefined

Git Hooks 完全指南

TypeScript 使用指南

undefined

undefined

章节编号

Chapter Numbering

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

Level	Format	Example
Level 1 Chapter	Numeric numbering	`## 1. 概述`
Level 2 Chapter	Dot-separated	`### 1.1 什么是 XX`
Level 3 Chapter	Dot-separated	`#### 1.1.1 详细说明`

结尾部分

Conclusion Section

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

Summary Chapter: Recap key points, may include a cheat sheet
Reference Resources Chapter: Provide links to official documentation and related resources

不使用的元素

Elements to Avoid

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

Do not use a table of contents
Do not use section dividers (
```
---
```
)

内容格式

Content Format

表格

Tables

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

Use markdown tables extensively for comparative explanations, parameter descriptions, and quick-reference summaries.

图解

Diagrams

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

Simple diagrams: Prefer ASCII art (Git branch diagrams, flowcharts)
Complex graphics: Use Mermaid syntax (class diagrams, sequence diagrams, flowcharts)

代码块

Code Blocks

javascript

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

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

要点：

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

javascript

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

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

Key points:

Specify the language type (bash, json, javascript, etc.)
- If JSON comments are needed, use
```
jsonc
```
Only include necessary key code
Use Chinese comments to explain key steps
Mark good/bad practices with
```
// ✅
```
and
```
// ❌
```

嵌套代码块

Nested Code Blocks

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

markdown

````markdown

When displaying Markdown examples that contain code blocks in the document, use 4 backticks for the outer layer and 3 backticks for the inner layer:

markdown

````markdown

示例标题

bash

python scripts/example.py

undefined

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

bash

python scripts/example.py

undefined

Note: The number of backticks at the start and end of nested code blocks must be the same, otherwise rendering errors will occur.

提示信息

Tip Messages

使用引用块格式：

markdown

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

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

> 说明：补充说明信息

Use blockquote format:

markdown

> **注意**：重要警告或注意事项
> **提示**：有用的建议
> 说明：补充说明信息

对比说明

Comparative Explanations

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

Use ✅ and ❌ to mark good/bad practices, which can be used in the main text or code comments.

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

FAQ (Optional, Q&A can deepen technical understanding)

markdown

**Q1: 问题内容？**

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

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

markdown

**Q1: 问题内容？**

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

Questions should focus on technical implementation, common error troubleshooting, configuration issues, and other technical content (related to the current technical topic).

速查表

Cheat Sheet

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

Provide a table-formatted quick reference in the summary chapter.

示例规范

Example Specifications

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

Provide complete, runnable code examples
Include multiple real-world application scenarios (Scenario 1, Scenario 2...)
Use Chinese comments in code examples to explain key steps
Provide step-by-step instructions (1. 2. 3.) for complex operations