tech-docs-guide

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: 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

# Git Hooks 完全指南

# TypeScript 使用指南

Chapter Numbering

## 1. 概述

### 1.1 什么是 XX

#### 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

Diagrams

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

Code Blocks

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

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

• 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
## 示例标题

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

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

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

Comparative Explanations

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

**Q1: 问题内容？**

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

Cheat Sheet

Example Specifications

• 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