PPTX/openspec/changes/archive/2026-03-06-refactor-docs-progressive-disclosure/proposal.md at 124ef0e5ce2206a25b4b0cecaa8fdfae3d949fbf

Files

lanyuanxiaoyao 124ef0e5ce refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷：
- 用户文档迁移到 docs/ (用户指南、元素、模板、参考等)
- 开发文档迁移到 docs/development/ (架构、模块、规范)
- README.md 精简至 ~290 行，仅保留概览和导航
- 删除 README_DEV.md，内容已迁移
- 归档 OpenSpec 变更 refactor-docs-progressive-disclosure

2026-03-06 15:11:36 +08:00

2.2 KiB

Raw Blame History

Why

当前项目的两个主要文档 README.md (1102 行) 和 README_DEV.md (1249 行) 体积过于庞大，包含了大量细节内容。这种"信息过载"的结构不便于人类和 AI 阅读与导航，违背了渐进式披露（Progressive Disclosure）的设计原则。用户无法快速获取核心信息，开发者也难以定位具体的开发指南。

What Changes

精简 README.md 到约 300 行：保留项目概览、功能特性、快速开始、核心概念，移除详细内容到子文档
创建 docs/ 目录结构：建立层次化的用户文档目录，按主题拆分内容
模块化拆分：
- 元素类型文档到 docs/elements/ (text.md, image.md, shape.md, table.md)
- 模板系统文档到 docs/templates/ (inline.md, external-library.md, mixing-mode.md, condition-rendering.md)
- 字体主题系统到 docs/fonts.md
- API 参考文档到 docs/reference/ (commands.md, coordinates.md, colors.md, validation.md)
- 示例和故障排查到 docs/examples.md 和 docs/troubleshooting.md
重构 README_DEV.md 到 docs/development/：
- 架构设计到 docs/development/architecture.md
- 模块详解到 docs/development/modules/ (elements.md, template.md, validators.md, renderers.md, loaders.md)
- 字体系统和作用域系统到独立文件
- 开发指南、扩展指南、测试规范、维护指南分别到独立文件
保持明确划分：用户文档 (docs/) 和开发文档 (docs/development/) 完全分离，面向不同的读者群体
使用纯 Markdown：不引入文档生成工具，保持简单

Capabilities

New Capabilities

(无 - 本变更仅涉及文档结构重组，不引入新的功能规范)

Modified Capabilities

(无 - 本变更不改变任何现有功能的需求规范)

Impact

文档结构：从 2 个巨型文件变为约 25 个模块化文档文件
导航体验：用户和开发者可以更快地定位所需信息
代码功能：无任何影响，不涉及代码修改
CI/CD：可能需要更新任何硬编码文档路径的自动化脚本
外部链接：项目主页的 README 会显示更简洁的内容，详细内容需要进入子目录查看

2.2 KiB Raw Blame History Unescape Escape

Why