文档编写与排序规范

本文面向仓库维护者，用于统一文档命名、展示顺序和阅读路径设计。

主要作用是：

• 给维护者统一文档命名方式
• 约束首页文档展示顺序
• 避免新文档把新手带进高级坑

维护仓库中的文档时，建议先核对这里的规则。

核心规则

1. 文档展示顺序不是按字母，而是按学习路径

同一分类下，文档必须遵守：

新手先看 -> 日常使用 -> 维护排障 -> 进阶方案 -> 旧版参考

这条规则优先于文件名字母顺序。

2. 标题必须一眼看出用途

标题不要只写成笼统名词。

推荐标题风格：

• 入门
• 快速开始
• 部署指南
• 恢复指南
• 进阶版
• 旧版参考
• 排障

避免：

• 两篇文档标题几乎一样
• 标题无法看出是否适合新手
• 旧方案和新方案名字太接近

3. 高风险文档必须显式标明等级

例如：

• （进阶版）
• （旧版参考）
• （高风险）

这样读者在目录里就能立即判断是否该点进去。

4. 同一主题只能有一个主教程

同一个操作主题，必须有一个明确的“主文档”负责完整步骤，其余文档只做：

• 入口说明
• 适用范围说明
• 风险提示
• 跳转到主文档

不要把同一套操作步骤分别写进多个文档。

例如：

• 存储扩容的主文档可以负责“识别系统类型 + 选路线 + 主流程”
• extroot 文档只负责 squashfs + overlay 的进阶方案
• 系统维护文档只保留日常检查与跳转入口，不重复展开完整扩容步骤

当前推荐顺序

对于首页维护类文档，当前顺序应为：

1. docs/OpenWrt_Backup_Resotre.md
2. docs/System_Maintenance.md
3. docs/Storage_Expansion_Guide.md
4. docs/ExtendOverlaySize.md
5. docs/OpenWrt_AutoBackup.md

理由：

• 先给读者恢复和维护基础
• 再讲存储扩容总览
• 再讲 extroot 这种进阶方案
• 旧版自动备份参考放后面

新增文档时必须同步修改的地方

如果新增了用户可见文档，且它会出现在首页目录中，必须同时检查：

1. README.md
2. README_EN.md
3. frontend/lib/docs.ts
4. 对应的更新日志 changelogs/*.md

如果新文档属于某个学习路径中的一环，还必须确认它在前端展示中的顺序是否正确。 如果新文档会和已有文档讨论同一主题，还必须先确认“主文档”是谁，避免出现两篇内容高度重复的教程。

前端排序机制

首页文档顺序不是自动猜的，而是显式维护的。

请同步维护：

• frontend/lib/docs.ts 中的 DOC_CATALOG_ORDER

如果你只新增文档文件，但不更新这个顺序表，新文档可能会排到不合适的位置。

命名示例

好的标题示例：

• ImmortalWrt 存储扩容与分区入门
• ImmortalWrt Overlay 与 Extroot 扩容（进阶版）
• ImmortalWrt GitHub 自动备份（旧版参考）

不好的标题示例：

• 智能自动备份
• 扩容教程
• 系统说明

因为这些名字太宽泛，读者很难判断差异。

一句话原则

这个仓库的文档排序目标不是“看起来整齐”，而是：

让新手按照正确顺序阅读，尽量少踩坑。