lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
8.2 KiB
8.2 KiB
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 保留内容:
- 项目标题和一句话描述
- 功能特性列表（精简）
- 快速开始（安装、5 分钟上手、实时预览）
- 核心概念概述（YAML 语法、元素类型、模板系统，各控制在 50 行内）
- 文档导航（分类链接到 docs/）
- 常见用例（3-5 个示例）
- 项目信息（依赖、许可证）
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. 内容迁移策略
决策: 先创建新结构，再移动内容，最后清理原文件
理由:
- 降低操作风险，随时可以回滚
- 确保没有内容遗漏
迁移顺序:
- 创建完整的目录结构
- 创建空的目标文件（带模板头部）
- 按主题从源文件复制内容到目标文件
- 更新所有交叉引用链接
- 精简 README.md 到 300 行
- 删除 README_DEV.md（内容已迁移）
- 验证所有链接有效性
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
-
是否需要文档搜索功能？
- 纯 Markdown 项目无法提供搜索，依赖 GitHub 的代码搜索
- 用户反馈后可考虑引入文档生成工具
-
示例文档策略？
- 目前未设计专门的示例文件
docs/examples.md作为占位文档，未来可根据用户需求添加- 各主题文档中已内嵌代码示例供参考
-
文档版本策略？
- 当前项目尚未发布，暂不考虑多版本文档
- 未来发布后，可能需要为不同主版本维护独立文档分支