类视搜图

简体中文

English

简体中文

English

📝 内部文档编写规范 ​

本文档定义了 docs-internal/ 中文档的编写规范和最佳实践。

🎯 文档分类 ​

1. 配置文档 ​

用途: 说明项目的配置方法和原理

命名: XXX配置说明.md 或 XXX_CONFIGURATION.md

模板:

markdown
# XXX配置说明

## 配置概述
简要说明配置的目的和作用

## 配置文件
列出相关的配置文件及其路径

## 配置项说明
详细说明每个配置项的含义

## 配置示例
提供完整的配置示例

## 常见问题
配置过程中可能遇到的问题

2. 部署文档 ​

用途: 说明如何将项目部署到服务器

命名: XXX部署指南.md 或 XXX_DEPLOYMENT.md

模板:

markdown
# XXX部署指南

## 部署方案
说明可选的部署方案及对比

## 部署步骤
详细的部署步骤说明

## 服务器配置
Nginx/Apache等服务器配置示例

## 验证清单
部署后的验证项目

3. 开发指南 ​

用途: 说明开发流程和规范

命名: XXX开发指南.md 或 XXX_DEVELOPMENT.md

4. 故障排查 ​

用途: 记录常见问题和解决方案

命名: 故障排查.md 或 TROUBLESHOOTING.md

📋 文档结构规范 ​

必需部分 ​

  1. 标题和概述

    markdown
    # 文档标题

> 一句话概述文档内容

## 📋 概述
详细说明文档的目的和适用范围

  2. 内容主体

    • 使用清晰的层级结构（##, ###）
    • 使用列表、表格、代码块等格式化内容
    • 添加emoji增强可读性（可选）

  3. 页脚信息

    markdown
    ---
**最后更新**: YYYY-MM-DD
**维护者**: 开发团队

可选部分 ​

  • 📋 快速开始
  • ⚙️ 配置说明
  • 🚀 使用方法
  • ⚠️ 注意事项
  • 🐛 故障排查
  • 📚 相关资源

✍️ 编写规则 ​

1. 语言规范 ​

  • ✅ 使用清晰、简洁的语言
  • ✅ 技术术语保持一致
  • ✅ 中英文混合时，英文单词前后加空格
  • ✅ 代码块必须指定语言类型

2. 格式规范 ​

markdown
✅ 正确示例：

## 配置文件路径

配置文件位于 `.vitepress/config-cn.ts`，主要包含以下配置项：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `lang` | 语言设置 | `zh-CN` |

❌ 错误示例：

配置文件在.vitepress/config-cn.ts,包含lang配置项(默认zh-CN)

3. 代码块规范 ​

markdown
✅ 正确：指定语言类型

```typescript
export default defineConfig({
  lang: 'zh-CN'
})
```

❌ 错误：不指定语言

```
export default defineConfig({
  lang: 'zh-CN'
})
```

4. 链接规范 ​

markdown
✅ 正确：使用相对路径

查看 [快速开始](./QUICK_START.md)

❌ 错误：使用绝对路径

查看 [快速开始](/docs-internal/QUICK_START.md)

🔄 文档更新流程 ​

1. 创建新文档 ​

bash
# 1. 在 docs-internal/ 中创建文档
touch docs-internal/新功能配置.md

# 2. 使用文档模板编写内容

# 3. 更新 README.md 的文档列表

2. 更新现有文档 ​

bash
# 1. 修改文档内容

# 2. 更新页脚的"最后更新"日期

# 3. 如有重大变更，在 README.md 的"文档更新记录"中添加记录

3. 归档旧文档 ​

bash
# 1. 创建归档目录
mkdir -p docs-internal/archive

# 2. 移动过时文档
mv docs-internal/旧文档.md docs-internal/archive/

# 3. 更新 README.md 文档列表

🤖 AI 编写提示词 ​

当使用 AI 助手编写文档时，可以使用以下提示词：

请按照 docs-internal/文档编写规范.md 的要求，
创建一个关于 [主题] 的 [类型] 文档，
包含以下部分：[列出需要的部分]

📚 参考示例 ​

好的文档示例 ​

  • ✅ DUAL_BUILD_DEPLOYMENT.md - 结构清晰，包含完整的配置示例
  • ✅ QUICK_START.md - 快速入门，步骤明确

需要改进的示例 ​

  • ⚠️ 缺少代码示例
  • ⚠️ 步骤不够详细
  • ⚠️ 缺少故障排查部分

✅ 文档质量检查清单 ​

在发布文档前，请检查：

  • [ ] 文档标题清晰明确
  • [ ] 包含概述部分
  • [ ] 代码块都指定了语言类型
  • [ ] 表格格式正确
  • [ ] 链接都可以正常访问
  • [ ] 包含实际可用的示例
  • [ ] 添加了"最后更新"日期
  • [ ] 语言表达清晰无歧义
  • [ ] 已添加到 README.md 文档列表

最后更新: 2025-01-10
维护者: 开发团队