# Doc Standard

> youlai-admin 项目文档写作规范。适用于编写 vue3-element-admin 操作指南、开发指南、AI 助手、项目部署、组件文档、Composable 文档、进阶定制和 FAQ 等各类文档。涵盖结构约束、禁止元素、栏目模板和内容归属规则。

- Skill: `youlaitech/doc-standard` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add youlaitech/doc-standard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/youlaitech/doc-standard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: youlaitech (https://skillmd.com/u/youlaitech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/youlaitech/doc-standard

---


# 文档写作规范

本规范约束 `youlai-admin-docs` 所有栏目的写作风格。目标：让读者快速找到代码、复制即用，不读废话。

## 核心原则

**读者带任务来，带代码走。** 文档存在的唯一价值是让读者尽快完成手头的事，而不是展示作者的知识体系。

代码给机器执行，文档给人理解。写文档时先想：读者为什么打开这页？他要走的时候手里该拿着什么？

## 文档分类框架

基于 [Diátaxis](https://diataxis.fr/) 框架，文档按读者需求分四种模式。**一篇文档只做一件事**，混合模式是质量下降的开始。

| 模式 | 读者问题 | 对应栏目 |
|------|----------|----------|
| 教程 | "教我怎么一步步做" | 操作指南（界面操作）、开发指南（写代码） |
| 操作指南 | "帮我完成这个任务" | 进阶定制 |
| 参考 | "这个组件/函数/配置项有哪些 API" | 组件文档、Composable 文档、系统设置、FAQ |
| 解释 | "团队约定是什么" | 代码规范 |

操作指南不混入原理，参考文档不混入教程。横切主题用交叉引用，不重复。

## 文档维护原则

借鉴 [Google 文档最佳实践](https://google.github.io/styleguide/docguide/best_practices.html)：

- **最小可用文档**：少量新鲜准确的文档 > 大量陈旧破损的文档。像修剪盆景一样持续维护
- **随代码更新**：文档变更与代码变更在同一个 PR，不滞后
- **删除死文档**：过时、错误、冗余的文档及时删除。死文档比没文档更糟——它误导读者
- **消灭重复**：链接而非复制。同一信息只在一处定义，其他地方交叉引用
- **写给人看**：代码能表达的不写文档（命名、类型签名）；文档写代码不能表达的（意图、约束、边界）

## 禁止出现的元素

以下元素一律删除，不留：

| 禁止项 | 示例 | 为什么禁止 |
|---|---|---|
| 「先看什么？」导航表 | `| 你要做什么 \| 推荐章节 \|` 整张表 | 目录大纲已能导航，重复一遍浪费版面。多页组件的模块索引除外（如 CURD 子页面导航） |
| 「介绍」「概览」纯描述段 | 「国际化能力覆盖语言包、运行时切换…」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、参数 | 只在「字段多、需要对照」时用 |

## 通用结构约束

所有文档必须遵循：

```markdown
---
title: 页面标题
---

# 页面标题

一句话说明这页讲什么、读者能做什么。不超过 2 行。

## 章节一
（代码 + 必要说明，不写「实现原理」）

## 章节二
（同上）
```

**硬规则**：

1. 文件开头 `title` 与 `# 标题`一致
2. 一句话引言后直接进章节，**不插入「介绍」「概览」「先看什么」**
3. 章节标题写「**做什么 / 是什么**」，不写「原理」「机制」「详解」
4. 代码块必须带语言标注（` ```typescript ` / ` ```vue `），TypeScript 统一用全称 `typescript`，不用缩写 `ts`
5. 代码示例值要具体（`ref(1)` 不要 `ref('')`），含注释说明值含义
6. 文档末尾**不加**「相关链接」「下一步」「源码位置」尾巴
7. 全文不出现 emoji（含代码注释中的正误符号）
8. 代码注释中标注正误时用文字而非符号：`// 推荐` / `// 不推荐`

## 目录与命名规范

- 所有目录和 `.md` 文件使用 kebab-case（小写 + 连字符）
- 文件名与 `title` frontmatter 保持语义一致
- 禁止同内容文件并存（如 `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](references/templates.md)。