文档编写规范

为知识库提供统一、可维护的写作标准。遵循本文规范可以确保所有文档易读、易查、易更新。

核心原则

• 内容优先：围绕一个主题写完整内容，只有当单文档超过 1000 行且出现多个独立子主题时再拆分。
• 可读性：标题层级清晰（H1 唯一，按序递进），合理使用目录、列表、引用块，突出重点信息。
• 可维护性：文件名、目录名使用 kebab-case，相对路径链接，图表和资源集中管理，定期回顾更新。
• 渐进式：先给出概览和核心结论，再补充背景、实现细节与扩展阅读，帮助读者逐步深入。

文件与目录

命名约定

• 文件夹、Markdown、图片一律 kebab-case：例如 front-end/runtime-overview.md、assets/architecture-diagram.png。
• 特殊保留：README.md（索引）、index.md（概述）、resources.md（资源列表）。
• 图片、附件放在同级 assets/ 目录，引用时使用相对路径。

目录结构建议

docs/
└── topic/
    ├── README.md        # 索引与导航
    ├── subject.md       # 主题全文（优先保持完整）
    ├── subtopic/        # 需要拆分时再建二级目录
    │   └── index.md
    └── assets/

- 同一主题优先放在单文件内，确需拆分时同步更新 README.md 导航。 - 面向读者的入口文件（README/index）保持轻量，指向更完整的主题文档。

内容结构

通用写作流程

1. 概览：一句话说明主题价值，可配一段背景或使用场景。
2. 主体：按逻辑分节，常见顺序为「核心概念 → 原理/流程 → 实践示例 → 最佳实践」。
3. 延伸：补充常见问题、对比、外部资源；必要时附上精简示例代码。

常用模板

# 标题
> 一句话概览

## 概述
- 背景 / 使用场景
- 关键价值

## 核心内容
### 小节 1
说明 + 代码/图示（可选）

### 小节 2
...

## 实践与最佳实践
- 建议 1
- 建议 2

## 常见问题 / 扩展阅读
- [资源链接](relative-path.md)

- 教程型文档可在主体部分改写为「前置知识 → 步骤 → 验证 → 拓展」。 - 参考资料型文档突出对比表、速查表，但保持主题单一。

写作要点

• 配图优先使用 Mermaid 或现成图示，确保文字说明可以独立理解。
• 代码块必须标注语言并聚焦核心逻辑，移除与主题无关的样板代码。
• 使用自然语言解释技术术语（例如 "SSE（Server-Sent Events）"），避免堆砌缩写。
• 链接到站内文档时一律使用相对路径，例如 前端工具总览。

面试题与问答类文档

• 70% 以上内容使用自然语言解释思路，代码仅作辅助。
• 推荐结构：核心思路 → 方案对比 → 技术要点 → 精简代码（可选） → 常见追问。
• 每个问题控制在 100-300 行内，突出决策理由与场景适用性。

发布前检查

• 文件名、目录名符合 kebab-case，入口文档已更新导航。
• 标题层级正确，H1 唯一；代码块均声明语言。
• 内部链接与资源路径使用相对地址并验证可用。
• 关键结论或最佳实践已突出呈现，避免冗长铺陈。
• 新内容与现有文档不存在语义冲突或重复。

最后更新：2024-10