制定时间: 2025-10-12
版本: v1.0
状态: 提案阶段
总文档数: 85+ 个 Markdown 文件
- 顶层 README: 1 个
- 模块 README: 33 个
- 架构文档: 3 个
- 开发指南: 5 个
- 进度追踪: 2 个
- 项目报告: 41 个 ⚠️ (过多)
问题:
- 大量临时性开发报告堆积
- 很多报告内容重复或过时
- 难以找到真正需要的信息
示例:
❌ DOCUMENTATION_FIX_2025-10-11.md
❌ DOCUMENTATION_REVIEW_2025-10-11.md
❌ DOCUMENTATION_UPDATE_SUMMARY.md
❌ DOCUMENTATION_UPDATE_COMPLETE_2025-10-12.md
❌ DOCUMENTATION_GAP_ANALYSIS_2025-10-12.md
❌ DOCUMENTATION_CODE_CONSISTENCY_CHECK.md
⬆️ 6 个关于文档的报告，内容高度重叠
问题:
- 有日期后缀和无日期后缀混用
- 中英文混用
- 大小写不统一
示例:
❌ PUSH_SCRIPT_FIX_2025-10-11.md (带日期)
❌ INPUT_SYSTEM_FIX.md (不带日期)
❌ UNIFIED_BUILD_SUMMARY_CN_2025-10-12.md (中文标记)
❌ UNIFIED_BUILD_SYSTEM_2025-10-12.md (无语言标记)
问题:
- 有些文档既是指南又是报告
- 缺少明确的读者定位
- 没有区分过期和有效文档
问题:
- 几乎每个目录都有 README
- 内容深度不一
- 更新不同步
问题:
- 没有全局的文档地图
- 新人难以快速找到需要的文档
- 文档间的关联不清晰
docs/
├── 1-permanent/ # 永久性文档（核心文档）
├── 2-reference/ # 参考文档（API、指南）
├── 3-progress/ # 进度文档（活跃更新）
├── 4-archive/ # 归档文档（历史记录）
└── 5-internal/ # 内部文档（开发笔记）
特征:
- 长期有效，反映项目核心设计
- 更新频率低，但需保持准确
- 面向所有用户
包含:
- 项目架构文档
- 核心概念说明
- 系统设计原理
- API 规范
示例:
architecture/
├── system-overview.md # 系统总览
├── compiler-design.md # 编译器设计
├── runtime-architecture.md # 运行时架构
└── component-model.md # 组件模型
特征:
- 查阅性文档，按需查找
- 内容详细、结构化
- 面向开发者
包含:
- 开发指南
- API 文档
- 配置说明
- 最佳实践
示例:
guides/
├── getting-started.md # 快速开始
├── build-system.md # 构建系统
├── component-development.md # 组件开发
└── troubleshooting.md # 故障排除
特征:
- 动态更新，反映当前状态
- 时效性强
- 面向团队和用户
包含:
- 开发进度
- 里程碑追踪
- 版本发布说明
- 路线图
示例:
progress/
├── roadmap.md # 路线图
├── milestones.md # 里程碑
├── changelog.md # 变更日志
└── current-sprint.md # 当前冲刺
特征:
- 历史记录，只读
- 已完成的工作记录
- 按年月组织
包含:
- 已完成的开发报告
- 历史问题修复记录
- 旧版本文档
示例:
archive/
├── 2025/
│ ├── 10-october/
│ │ ├── unified-build-implementation.md
│ │ ├── component-loading-fix.md
│ │ └── input-system-implementation.md
│ └── 11-november/
└── 2024/
特征:
- 临时性、非正式
- 开发过程中的笔记
- 不面向最终用户
包含:
- 调试日志
- 临时笔记
- 实验记录
- TODO 清单
d:\_Bit_OS\Bit HCI/
│
├── README.md # 🎯 项目入口（精简、清晰）
├── QUICK_START.md # ⚡ 5分钟快速开始
├── BUILD_GUIDE.md # 🔧 详细构建指南
├── CONTRIBUTING.md # 🤝 贡献指南
│
├── docs/ # 📚 文档中心
│ ├── README.md # 文档导航中心
│ │
│ ├── architecture/ # 🏛️ 架构设计（永久）
│ │ ├── README.md
│ │ ├── system-overview.md # 系统总览 ⭐
│ │ ├── compiler-architecture.md # 编译器架构 ⭐
│ │ ├── runtime-architecture.md # 运行时架构 ⭐
│ │ ├── component-model.md # 组件模型
│ │ └── rendering-pipeline.md # 渲染管线
│ │
│ ├── guides/ # 📖 开发指南（参考）
│ │ ├── README.md
│ │ ├── getting-started.md # 新手入门 ⭐
│ │ ├── build-system.md # 构建系统
│ │ ├── component-development.md # 组件开发
│ │ ├── compiler-usage.md # 编译器使用
│ │ ├── debugging.md # 调试技巧
│ │ └── troubleshooting.md # 故障排除
│ │
│ ├── api/ # 🔌 API 文档（参考）
│ │ ├── README.md
│ │ ├── runtime-api.md # 运行时 API
│ │ ├── component-api.md # 组件 API
│ │ └── compiler-api.md # 编译器 API
│ │
│ ├── progress/ # 📊 进度追踪（动态）
│ │ ├── README.md
│ │ ├── roadmap.md # 路线图 ⭐
│ │ ├── milestones.md # 里程碑
│ │ ├── changelog.md # 变更日志
│ │ └── status.md # 当前状态
│ │
│ ├── archive/ # 🗄️ 历史归档（只读）
│ │ ├── README.md
│ │ └── 2025/
│ │ └── 10-october/
│ │ ├── unified-build-implementation.md
│ │ ├── component-loading-fix.md
│ │ └── ...
│ │
│ └── internal/ # 🔒 内部笔记（可选）
│ ├── README.md
│ ├── dev-notes/
│ └── experiments/
│
├── compiler/ # 编译器模块
│ └── README.md # 模块说明
│
├── native/ # 运行时模块
│ └── README.md # 模块说明
│
├── examples/ # 示例组件
│ ├── README.md # 示例总览
│ ├── cpp/ # C++ 组件
│ │ ├── README.md # C++ 组件指南
│ │ └── [component]/
│ │ └── README.md # 单个组件文档
│ └── bit/ # BitUI 组件
│ └── README.md # BitUI 组件指南
│
├── scripts/ # 构建脚本
│ └── README.md # 脚本使用说明
│
└── [其他模块]/
└── README.md
✅ 永久性文档 (architecture/): 5-8 个
✅ 参考文档 (guides/ + api/): 10-15 个
✅ 进度文档 (progress/): 4-5 个
✅ 归档文档 (archive/): 按月归档，不限
✅ 模块 README: 每个主要模块 1 个
✅ 组件 README: 每个组件 1 个（可选）
🎯 总计活跃文档: 约 30-40 个（不含归档）
规则 1: 使用 kebab-case（小写加连字符）
✅ system-overview.md
❌ System_Overview.md
❌ SystemOverview.md
规则 2: 文件名要描述性强
✅ getting-started.md
✅ component-development-guide.md
❌ guide1.md
❌ doc.md
规则 3: 避免日期后缀（除非归档）
活跃文档:
✅ changelog.md (内部有日期)
❌ changelog-2025-10-12.md
归档文档:
✅ 2025/10-october/build-system-refactor.md
❌ BUILD_SYSTEM_2025-10-12.md
规则 4: 语言标记放在前缀
✅ api-reference.md (默认英文)
✅ api-reference.zh-CN.md (中文版)
❌ api-reference-CN.md
规则 5: README.md 特殊规则
- 每个主要目录有且仅有一个
- 名称固定为 README.md
- 内容为该目录的导航/说明architecture/ # 无前缀（默认架构文档）
guides/ # 无前缀（默认指南文档）
progress/ # 无前缀（默认进度文档）
archive/2025/10-october/
- [component]-feature-name.md # 功能实现
- [module]-bug-fix.md # 问题修复
- [system]-refactoring.md # 重构记录
[创建] → [活跃] → [稳定] → [过时] → [归档]
↓ ↓ ↓ ↓ ↓
草稿 持续更新 偶尔更新 停止更新 只读存储
---
status: draft
author: 作者名
created: 2025-10-12
last_updated: 2025-10-12
---
# 文档标题 [DRAFT]
**⚠️ 本文档处于草稿状态，内容可能不完整或有错误。**---
status: active
author: 作者名
created: 2025-10-12
last_updated: 2025-10-12
review_cycle: monthly # 审查周期
---
# 文档标题
正常文档内容...---
status: stable
version: 1.0
author: 作者名
created: 2025-10-12
last_updated: 2025-10-12
review_cycle: quarterly # 季度审查
---
# 文档标题
✅ 本文档已稳定，内容准确可靠。---
status: deprecated
deprecated_date: 2025-12-01
replacement: path/to/new-doc.md
---
# 文档标题 [DEPRECATED]
**⚠️ 本文档已过时，请参考：[新文档](path/to/new-doc.md)**
---
原内容保留供参考...---
status: archived
archived_date: 2025-11-01
original_location: docs/reports/
---
# [归档] 文档标题
**📦 本文档已归档，仅供历史参考。**
**完成时间**: 2025-10-12
**相关版本**: v0.0.1
---
原内容...每个文档顶部添加元数据块：
---
title: 文档标题
status: active | stable | draft | deprecated | archived
type: architecture | guide | api | progress | report
audience: all | developer | contributor | internal
version: 1.0
author: 作者名
created: 2025-10-12
last_updated: 2025-10-12
last_reviewed: 2025-10-12
review_cycle: weekly | monthly | quarterly | yearly
tags: [tag1, tag2, tag3]
---# scripts/check-docs.ps1
功能:
- 检查所有文档的元数据
- 检测过期文档（last_updated > 90天）
- 检测缺失 README
- 检测断链
- 生成文档健康报告# scripts/generate-doc-index.ps1
功能:
- 扫描所有文档
- 生成 docs/README.md（自动更新）
- 生成按标签分类的索引
- 生成文档依赖图每周审查:
- progress/ 下的所有文档
- 检查是否需要更新里程碑
每月审查:
- guides/ 下的活跃文档
- 检查示例代码是否仍然有效
每季度审查:
- architecture/ 下的所有文档
- 确保与代码实现一致
每半年审查:
- 所有 active 状态文档
- 决定是否转为 stable 或 deprecatedgraph LR
A[识别过时文档] --> B[标记 deprecated]
B --> C[等待 1 个月]
C --> D{仍需保留?}
D -->|是| E[移至 archive/]
D -->|否| F[删除]
E --> G[更新索引]
F --> G
归档规则：
1. 开发报告类文档（已完成的）
- 立即归档到 archive/YYYY/MM-month/
2. 实现记录类文档（功能已合并）
- 保留 1 个月后归档
3. 临时指南类文档（已被新指南替代）
- 标记 deprecated，链接到新文档
- 3 个月后归档或删除
4. 实验性文档（实验已结束）
- 移至 internal/experiments/archive/目标: 搭建新的文档结构
第 1 步: 创建新目录结构
- 创建 docs/architecture/
- 创建 docs/guides/
- 创建 docs/api/
- 创建 docs/progress/
- 创建 docs/archive/2025/10-october/
- 创建 docs/internal/
第 2 步: 开发自动化工具
- scripts/check-docs.ps1
- scripts/generate-doc-index.ps1
- scripts/archive-docs.ps1
第 3 步: 制定文档模板
- docs/templates/architecture-template.md
- docs/templates/guide-template.md
- docs/templates/api-template.md目标: 审查现有文档，分类整理
第 1 步: 审查所有现有文档
✅ 阅读每个文档
✅ 评估其价值和时效性
✅ 决定其归属和状态
第 2 步: 分类决策
永久性文档（保留并重写）:
- docs/architecture/ 下 3 个
- 需要重新编写，确保准确性
参考文档（保留并更新）:
- docs/guides/ 下 5 个
- 更新过时内容
进度文档（保留并精简）:
- docs/progress/ 下 4 个
- 合并重复内容
归档文档（移动）:
- docs/archive/2025/10-october/ 约 30 个
- 已完成的报告全部归档
删除文档（慎重）:
- 完全过时且无参考价值的
- 内容重复的（保留最新的）
第 3 步: 创建文档清单
- 列出需要保留的文档
- 列出需要重写的文档
- 列出需要归档的文档
- 列出需要删除的文档目标: 执行文档重组
第 1 步: 归档历史文档
- 将 41 个报告分类归档
- 更新归档文档的元数据
第 2 步: 重写核心文档
优先级：
1. README.md (项目入口)
2. QUICK_START.md (快速开始)
3. docs/architecture/system-overview.md
4. docs/guides/getting-started.md
5. docs/progress/roadmap.md
第 3 步: 更新参考文档
- 更新所有 guides/
- 创建 api/ 文档
第 4 步: 更新模块 README
- 精简模块 README
- 确保一致性目标: 确保文档可持续维护
第 1 步: 配置自动化
- 设置文档检查的 Git Hook
- 配置 CI 自动生成索引
第 2 步: 编写维护指南
- docs/internal/documentation-guidelines.md
- 包含如何创建、更新、归档文档
第 3 步: 培训和推广
- 更新 CONTRIBUTING.md
- 说明文档贡献流程目标: 确保新体系运行良好
第 1 步: 全面测试
- 检查所有链接
- 验证文档层次
- 测试自动化脚本
第 2 步: 收集反馈
- 团队内部试用
- 调整不合理的地方
第 3 步: 最终发布
- 提交所有更改
- 更新项目主页
- 公告新文档体系当前状态:
总文档: 85+ 个
- 活跃文档: 85 个（全部混在一起）
- 归档文档: 0 个
- 问题: 难以管理，查找困难
目标状态:
总文档: 85+ 个（数量不变，但结构清晰）
- 活跃文档: 30-40 个（精简、准确）
- 永久文档: 8 个
- 参考文档: 15 个
- 进度文档: 5 个
- 模块文档: 10 个
- 归档文档: 40-50 个（按时间组织）
- 优势: 清晰、易查找、易维护
可查找性: ⭐⭐⭐⭐⭐ (5/5)
- 新人 5 分钟找到需要的文档
准确性: ⭐⭐⭐⭐⭐ (5/5)
- 文档与代码 100% 一致
完整性: ⭐⭐⭐⭐☆ (4/5)
- 覆盖所有主要模块和功能
可维护性: ⭐⭐⭐⭐⭐ (5/5)
- 有明确的更新流程和自动化支持
可扩展性: ⭐⭐⭐⭐⭐ (5/5)
- 新文档有明确的归属位置
- 创建新目录结构
- 开发文档检查脚本
- 开发索引生成脚本
- 开发归档脚本
- 创建文档模板
- 完整阅读所有 85 个文档
- 创建文档分类清单
- 标记需要重写的文档
- 标记需要归档的文档
- 标记需要删除的文档
- 归档历史报告（40+ 个）
- 重写项目入口文档（README.md）
- 重写快速开始文档
- 重写架构文档（5-8 个）
- 更新开发指南（10+ 个）
- 创建 API 文档
- 精简进度文档
- 更新所有模块 README
- 配置文档检查自动化
- 配置索引生成自动化
- 编写文档维护指南
- 更新贡献指南
- 运行自动化检查
- 手动验证所有链接
- 团队内部审查
- 修正发现的问题
- 最终发布
文档重组成功的标志：
✅ 1. 任何人 5 分钟内找到需要的文档
✅ 2. 所有文档有明确的状态标记
✅ 3. 文档与代码 100% 同步
✅ 4. 归档文档不干扰日常查找
✅ 5. 有清晰的文档更新流程
✅ 6. 自动化工具运行正常
✅ 7. 团队成员认可新体系
本方案是一个初始提案，需要根据实际执行情况不断调整。
反馈渠道:
- 创建 Issue 讨论
- 提交 PR 改进
- 团队内部会议讨论
改进周期:
- 执行后 1 周: 收集初步反馈
- 执行后 1 月: 第一次方案调整
- 执行后 3 月: 全面评估和优化
提案人: AI Assistant
提案时间: 2025-10-12
预计实施周期: 10-15 天
状态: 等待批准 🟡