youlaitech 文档写作规范
本规范约束 youlai-admin-docs 所有栏目的写作风格。目标：让读者快速找到代码、复制即用，不读废话。
核心原则
读者带任务来，带代码走。 文档存在的唯一价值是让读者尽快完成手头的事，而不是展示作者的知识体系。
代码给机器执行，文档给人理解。写文档时先想：读者为什么打开这页？他要走的时候手里该拿着什么？
文档分类框架
基于 Diátaxis 框架，文档按读者需求分四种模式。一篇文档只做一件事，混合模式是质量下降的开始。
| 模式 | 读者问题 | 对应栏目 |
|---|---|---|
| 教程 | "教我怎么一步步做" | 操作指南（界面操作）、开发指南（写代码） |
| 操作指南 | "帮我完成这个任务" | 进阶定制 |
| 参考 | "这个组件/函数/配置项有哪些 API" | 组件文档、Composable 文档、系统设置、FAQ |
| 解释 | "团队约定是什么" | 代码规范 |
操作指南不混入原理，参考文档不混入教程。横切主题用交叉引用，不重复。
文档维护原则
借鉴 Google 文档最佳实践：
- 最小可用文档：少量新鲜准确的文档 > 大量陈旧破损的文档。像修剪盆景一样持续维护
- 随代码更新：文档变更与代码变更在同一个 PR，不滞后
- 删除死文档：过时、错误、冗余的文档及时删除。死文档比没文档更糟——它误导读者
- 消灭重复：链接而非复制。同一信息只在一处定义，其他地方交叉引用
- 写给人看：代码能表达的不写文档（命名、类型签名）；文档写代码不能表达的（意图、约束、边界）
禁止出现的元素
以下元素一律删除，不留：
| 禁止项 | 示例 | 为什么禁止 |
|---|---|---|
| 「先看什么？」导航表 | ` | 你要做什么 | 推荐章节 |` 整张表 |
| 「介绍」「概览」纯描述段 | 「国际化能力覆盖语言包、运行时切换…」5 条 bullet | 读者点进来就知道这是什么，不需要再介绍一遍 |
| 「功能特性」列表 | ## 功能特性 + emoji bullet |
信息密度低，且大纲里已经能看出 |
| 「使用场景」段落 | ## 使用场景 或 > 💡 使用场景： |
读者自己判断场景，不需要作者教。进阶定制（recipes）开头说明适用场景除外 |
| 「快速摘要」复述目录 | ## 快速摘要 把章节再列一遍 |
跟「先看什么」一样，是目录的重复 |
| ASCII 架构图 | ┌──┐│ │└──┘ 框线图 |
难维护、占版面、移动端错位；用 mermaid 或直接列表 |
| 「下一步」「相关链接」尾巴 | ## 下一步 / ## 相关链接 + 3~5 个跳转 |
读者会用搜索和侧边栏，不需要作者推荐 |
| 「实现原理」长篇 | ### 实现原理 + 50 行源码引用 |
操作指南只讲「怎么用」，原理类内容写进博客或独立栏 |
| emoji 装饰 | ## 🎯 在线体验 / > 💡 提示： |
干扰阅读，正式文档不用 |
| 「源码位置」清单 | ## 源码位置 + 4 条文件路径 |
读者会用 IDE 全局搜索 |
| 「常见问题」放正文 | ## 常见问题 + 3~5 个 Q&A |
FAQ 应集中在 /faq/ 栏，不污染操作文档 |
| 「总结」复述全文 | ## 总结 把全文规则再列一遍 |
跟「快速摘要」一样，是内容的重复 |
| 「参考来源」列表 | ## 参考来源 + 8 个外链 |
规范条款本身就是来源，不需要参考文献 |
| 「为什么这样设计」解释段 | 「之所以这样区分是因为…」 | 规范文档给规则，不给理由 |
| 博客式过渡句 | 「下面我们来看…」「接下来将详细分析…」 | 直接给内容，不要描述即将做什么 |
| 空话引言 | 「了解如何构建和部署项目」 | 标题已说明，引言要给增量信息 |
允许但克制的元素
| 元素 | 何时使用 | 限制 |
|---|---|---|
| 一句话引言 | 章节开头点明「这是什么、能做什么」 | 不超过 2 行，不堆砌特性形容词 |
| mermaid 流程图 | 真正复杂的流程（登录、动态路由生成） | 一图胜千言时才用，简单流程直接列表 |
注意事项 ::: tip |
真正会踩坑的点（如 BOM、编码、必填字段） | 每页不超过 1 个，不用于常识性提醒 |
| 表格 | 对比配置项、Props、参数 | 只在「字段多、需要对照」时用 |
通用结构约束
所有文档必须遵循：
---
title: 页面标题
---
# 页面标题
一句话说明这页讲什么、读者能做什么。不超过 2 行。
## 章节一
（代码 + 必要说明，不写「实现原理」）
## 章节二
（同上）
硬规则：
- 文件开头
title与# 标题一致 - 一句话引言后直接进章节，不插入「介绍」「概览」「先看什么」
- 章节标题写「做什么 / 是什么」，不写「原理」「机制」「详解」
- 代码块必须带语言标注（
```typescript/```vue），TypeScript 统一用全称typescript，不用缩写ts - 代码示例值要具体（
ref(1)不要ref('')），含注释说明值含义 - 文档末尾不加「相关链接」「下一步」「源码位置」尾巴
- 全文不出现 emoji（含代码注释中的正误符号）
- 代码注释中标注正误时用文字而非符号：
// 推荐/// 不推荐
目录与命名规范
- 所有目录和
.md文件使用 kebab-case（小写 + 连字符） - 文件名与
titlefrontmatter 保持语义一致 - 禁止同内容文件并存（如
index.md与introduction.md重复） - 遗留文件及时清理（已合并的旧模板应删除）
内容归属规则
当某个主题横跨两个文档类型时，按主操作归属，另一篇用交叉引用：
| 横切主题 | 归属文档 | 另一篇处理方式 |
|---|---|---|
| 菜单标题国际化 | i18n.md |
router-menu.md 一句话 + 链接 |
| 环境变量 | settings.md |
deploy.md 引用 |
| Nginx 配置 | deploy.md |
settings.md 不重复 |
| 按钮权限与权限标识 | permission.md |
router-menu.md 引用 |
交叉引用格式：详见[新增菜单](/element/guide/router-menu#菜单标题国际化)，不单独开「相关链接」章节。
栏目模板
7 种栏目模板（操作指南、开发指南、项目部署、组件文档、Composable 文档、进阶定制、FAQ）定义了每种文档的结构、写作规则和字数控制。详见 templates.md。