refactor: 重构文档结构，采用渐进式信息披露模式
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
@@ -0,0 +1,229 @@
|
||||
## Context
|
||||
|
||||
**当前状态**:
|
||||
|
||||
项目目前有两个主要文档文件：
|
||||
- `README.md` (1102 行) - 面向终端用户，包含安装、使用、API 文档等
|
||||
- `README_DEV.md` (1249 行) - 面向开发者，包含架构、开发规范、测试等
|
||||
|
||||
这种"巨型单文件"结构导致：
|
||||
- 新用户需要滚动大量内容才能找到快速开始指南
|
||||
- 开发者难以在 1249 行中定位特定的模块说明
|
||||
- AI 处理长文档时容易丢失上下文
|
||||
- 违反渐进式披露设计原则
|
||||
|
||||
**约束条件**:
|
||||
- 不引入文档生成工具（MkDocs、Docusaurus 等），保持纯 Markdown
|
||||
- 不修改代码功能
|
||||
- 保持用户文档和开发文档的明确划分
|
||||
- 项目尚未上线，无现有用户需要迁移
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- README.md 精简到约 300 行，聚焦快速开始和核心概念
|
||||
- 建立清晰的文档导航结构，用户能在 3 次点击内找到所需信息
|
||||
- 按主题模块化拆分文档，每个文件控制在 100-300 行
|
||||
- 保持文档内容的完整性和准确性，只重组不删除
|
||||
|
||||
**Non-Goals:**
|
||||
- 不改变代码行为或 API
|
||||
- 不引入新的文档工具链
|
||||
- 不创建多语言版本
|
||||
- 不改变项目现有的开发规范
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 文档目录结构
|
||||
|
||||
**决策**: 采用两层目录结构 `docs/` 和 `docs/development/`
|
||||
|
||||
**理由**:
|
||||
- 用户文档和开发文档读者群体不同，分离后避免相互干扰
|
||||
- 两层结构比单层更清晰，比三层更简洁
|
||||
- 与 GitHub/GitLab 的文档展示方式兼容
|
||||
|
||||
**替代方案考虑**:
|
||||
- 单层 `docs/` 目录：会导致用户和开发文档混在一起，增加认知负担
|
||||
- 三层结构（如 `docs/user/guide/`）：对于纯 Markdown 项目过于复杂，导航困难
|
||||
|
||||
### 2. README.md 内容策略
|
||||
|
||||
**决策**: 保留"概览 + 快速开始 + 导航链接"结构
|
||||
|
||||
**理由**:
|
||||
- 项目首页需要给用户最核心的信息：这是什么、怎么快速开始、去哪里深入了解
|
||||
- 300 行限制确保在 GitHub 首页可以完整浏览而不需要大量滚动
|
||||
|
||||
**README.md 保留内容**:
|
||||
1. 项目标题和一句话描述
|
||||
2. 功能特性列表（精简）
|
||||
3. 快速开始（安装、5 分钟上手、实时预览）
|
||||
4. 核心概念概述（YAML 语法、元素类型、模板系统，各控制在 50 行内）
|
||||
5. 文档导航（分类链接到 docs/）
|
||||
6. 常见用例（3-5 个示例）
|
||||
7. 项目信息（依赖、许可证）
|
||||
|
||||
### 3. 拆分粒度
|
||||
|
||||
**决策**: 按主题拆分，每个文件 100-300 行
|
||||
|
||||
**理由**:
|
||||
- 按主题拆分符合用户的思维模型（"我需要了解模板系统" → 打开 templates/）
|
||||
- 100-300 行确保每个文件专注单一主题，易于维护
|
||||
- 过细的拆分（如 50 行一个文件）会导致文件碎片化，增加导航负担
|
||||
|
||||
**具体拆分方案**:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── user-guide.md (200-300行) - 用户完整指南
|
||||
├── elements/ - 按元素类型拆分
|
||||
│ ├── text.md (100-150行)
|
||||
│ ├── image.md (100-150行)
|
||||
│ ├── shape.md (100-150行)
|
||||
│ └── table.md (100-150行)
|
||||
├── templates/ - 按模板功能拆分
|
||||
│ ├── inline.md (150-200行)
|
||||
│ ├── external-library.md (150-200行)
|
||||
│ ├── mixing-mode.md (150-200行)
|
||||
│ └── condition-rendering.md (150-200行)
|
||||
├── fonts.md (200行) - 字体主题系统
|
||||
├── reference/ - API 参考文档
|
||||
│ ├── commands.md (50-100行)
|
||||
│ ├── coordinates.md (50-100行)
|
||||
│ ├── colors.md (50-100行)
|
||||
│ └── validation.md (50-100行)
|
||||
├── examples.md (200行) - 示例集合
|
||||
└── troubleshooting.md (100行) - 故障排查
|
||||
|
||||
docs/development/
|
||||
├── architecture.md (300行) - 架构设计
|
||||
├── modules/ - 按代码模块拆分
|
||||
│ ├── elements.md (100-200行)
|
||||
│ ├── template.md (100-200行)
|
||||
│ ├── validators.md (100-200行)
|
||||
│ ├── renderers.md (100-200行)
|
||||
│ └── loaders.md (100-200行)
|
||||
├── font-system.md (150行) - 字体系统实现
|
||||
├── scope-system.md (200行) - 作用域系统
|
||||
├── development-guide.md (150行) - 开发规范
|
||||
├── extending.md (200行) - 扩展指南
|
||||
├── testing.md (200行) - 测试规范
|
||||
└── maintenance.md (100行) - 维护指南
|
||||
```
|
||||
|
||||
### 4. 文档间链接策略
|
||||
|
||||
**决策**: 使用相对路径链接，创建导航辅助文件
|
||||
|
||||
**理由**:
|
||||
- 相对路径在 Git clone 后仍然有效
|
||||
- 每个目录下的 `index.md` 或 `_nav.md` 提供该目录的导航
|
||||
|
||||
**实现**:
|
||||
- 在每个子目录创建索引文件（如 `docs/elements/_index.md`）列出该目录下的所有文档
|
||||
- README.md 中的链接使用 `./docs/...` 相对路径
|
||||
- 文档间的交叉引用也使用相对路径
|
||||
|
||||
### 5. 内容迁移策略
|
||||
|
||||
**决策**: 先创建新结构，再移动内容，最后清理原文件
|
||||
|
||||
**理由**:
|
||||
- 降低操作风险，随时可以回滚
|
||||
- 确保没有内容遗漏
|
||||
|
||||
**迁移顺序**:
|
||||
1. 创建完整的目录结构
|
||||
2. 创建空的目标文件（带模板头部）
|
||||
3. 按主题从源文件复制内容到目标文件
|
||||
4. 更新所有交叉引用链接
|
||||
5. 精简 README.md 到 300 行
|
||||
6. 删除 README_DEV.md（内容已迁移）
|
||||
7. 验证所有链接有效性
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1: 外部链接失效
|
||||
|
||||
**风险**: 项目外部的博客、教程引用了原 README.md 的特定章节，迁移后这些链接会失效。
|
||||
|
||||
**缓解措施**:
|
||||
- 项目尚未上线，无外部引用
|
||||
- 在 README.md 顶部添加迁移说明（如果未来有外部引用）
|
||||
- 考虑保留原文件的 Git 历史供追溯
|
||||
|
||||
### 风险 2: 用户找不到信息
|
||||
|
||||
**风险**: 用户习惯了在 README.md 中查找所有信息，迁移后可能不知道去哪里找详细内容。
|
||||
|
||||
**缓解措施**:
|
||||
- README.md 保留清晰的文档导航区块，分类列出所有子文档
|
||||
- 每个子文档顶部有"返回导航"链接
|
||||
- 在 `docs/README.md` 创建完整文档索引
|
||||
|
||||
### 风险 3: 维护负担增加
|
||||
|
||||
**风险**: 文件数量从 2 个增加到约 25 个，可能增加维护成本。
|
||||
|
||||
**缓解措施**:
|
||||
- 每个文件职责明确，单一主题，降低修改时的认知负担
|
||||
- 使用相对路径链接，重命名时工具可自动更新
|
||||
- 定期审计文档结构，合并过于碎片化的文件
|
||||
|
||||
### 权衡: 简洁 vs 完整
|
||||
|
||||
**权衡**: README.md 精简后可能让部分用户感觉"信息不完整"。
|
||||
|
||||
**缓解措施**:
|
||||
- 在 README.md 中明确说明这是"快速入门"，完整文档在 docs/
|
||||
- 保持 docs/ 文档的完整性和详细程度
|
||||
- 提供"常见用例"覆盖 80% 用户的需求
|
||||
|
||||
## Migration Plan
|
||||
|
||||
### 阶段 1: 准备 (1-2 小时)
|
||||
|
||||
- [ ] 创建 `docs/` 和 `docs/development/` 目录结构
|
||||
- [ ] 创建所有目标文件的空模板（带标题和简要说明）
|
||||
- [ ] 在 `docs/README.md` 创建完整文档索引
|
||||
|
||||
### 阶段 2: 内容迁移 (3-4 小时)
|
||||
|
||||
- [ ] 按拆分方案从 README.md 复制内容到各子文档
|
||||
- [ ] 按拆分方案从 README_DEV.md 复制内容到各开发文档
|
||||
- [ ] 更新所有文档内部的交叉引用链接
|
||||
- [ ] 添加每个文档的导航链接（返回上级、相关文档）
|
||||
|
||||
### 阶段 3: 精简主文件 (1 小时)
|
||||
|
||||
- [ ] 精简 README.md 到约 300 行
|
||||
- [ ] 删除 README_DEV.md（内容已迁移）
|
||||
- [ ] 更新 README.md 中的文档导航链接
|
||||
|
||||
### 阶段 4: 验证 (30 分钟)
|
||||
|
||||
- [ ] 检查所有相对路径链接是否有效
|
||||
- [ ] 验证没有内容遗漏
|
||||
- [ ] 在 GitHub 上预览文档显示效果
|
||||
|
||||
### 回滚策略
|
||||
|
||||
- 保留 Git 历史，随时可以 `git checkout` 回原来的文档结构
|
||||
- 建议在新分支进行迁移，验证通过后再合并到主分支
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **是否需要文档搜索功能？**
|
||||
- 纯 Markdown 项目无法提供搜索，依赖 GitHub 的代码搜索
|
||||
- 用户反馈后可考虑引入文档生成工具
|
||||
|
||||
2. **示例文档策略？**
|
||||
- 目前未设计专门的示例文件
|
||||
- `docs/examples.md` 作为占位文档，未来可根据用户需求添加
|
||||
- 各主题文档中已内嵌代码示例供参考
|
||||
|
||||
3. **文档版本策略？**
|
||||
- 当前项目尚未发布，暂不考虑多版本文档
|
||||
- 未来发布后，可能需要为不同主版本维护独立文档分支
|
||||
Reference in New Issue
Block a user