PPTX/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/design.md

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. 文档版本策略？

   • 当前项目尚未发布，暂不考虑多版本文档
   • 未来发布后，可能需要为不同主版本维护独立文档分支