| name | doc-standard |
| description | 好文档写作与评审标准。用于：写作新文档、审查现有文档质量、修改文档内容、排版优化、添加 callout/图示。
触发场景：用户提到"写文档"、"审查文档"、"文档标准"、"好文档"、"排版"、"callout"、"文档质量"、"写作规范"时自动触发。
适用所有飞书文档和 Markdown 文档的创建与编辑。
|
好文档标准 v1.0
一句话锚点
好文档 = 让读者"记住并愿意用"，而不是"看完觉得全面"。
每一个写作选择——结构、措辞、配图、排版——都必须回答同一个问题：这一步，是帮读者记住，还是只是让文档看起来更完整？
核心五原则速查
| # | 原则 | 一句话 | 判断标准 |
|---|
| 1 | 先锚后展 | 每节第一句必须是核心结论，加粗钉住 | 只看第一句就离开，是否拿到了最重要的东西？ |
| 2 | 类比优先于列表 | "一次理解"用类比，"反复翻阅"用表格 | 读者合上文档，能回忆起哪个画面/比喻？ |
| 3 | 场景复现优于罗列 | 讲风险先还原真实场景，让读者"被吓到" | 读者脑中是否"播放"了一个画面？ |
| 4 | 用对比驱动改变 | 教学内容用 ❌反例 / ✅正例 对比呈现 | 读者是否意识到"我之前是错的"？ |
| 5 | 语气像人讲话 | 有停顿、有强调、有吐槽，朗读不别扭 | 听起来像"有人在跟我聊"还是"念说明书"？ |
快速执行指南
写作时
- 每个章节：先写加粗锚点句 → 再展开
- 讲概念：先给类比（一句话能记住的比喻），再列要点
- 讲风险：先复现场景（"它会一本正经地给你列 5 条引用，你去查，2 篇不存在"），再讲来源
- 教方法：❌反例 / ✅正例 相邻出现，形成视觉对比
- 结尾：不要硬加总结框架——如果文章本身够好，读者自然知道该怎么做
审查时
逐条过「发布前检查清单」（详见 references/checklist.md），任何一条不通过就回去改：
视觉规范速查
Callout 体系
| 类型 | 用途 | 背景色 | 边框色 | 图标 |
|---|
| 提示类 | 方法、技巧、可执行建议 | rgb(255,245,235) 暖橙 | rgb(255,186,107) | 🎯 🐾 |
| 引导类 | 补充说明、延伸阅读 | rgb(240,244,255) 浅蓝 | rgb(183,237,177) | 🧝 |
| 反例 | 错误示范、常见误区 | rgb(253,226,226) 浅红 | rgb(249,142,139) | ❌ |
| 正例 | 正确示范、推荐做法 | rgb(217,245,214) 浅绿 | rgb(142,224,133) | ✅ |
规则：
- 反例和正例必须相邻出现
- 提示类 callout 只用于可执行建议，不用于解释概念
- 每个章节内 callout ≤ 2 个
强调体系
| 元素 | 样式 | 用途 |
|---|
| 核心结论 | 加粗 | 每节的锚点句 |
| 关键词/易错点 | 红色 rgb(216,57,49) | 句内需要视觉跳转的词 |
| 术语首次出现 | 加粗 | 首次定义后不再强调 |
规则： 红色强调 ≤ 5 处/篇。超过就等于没有强调。
图示选择
| 信息类型 | 推荐形式 | 位置 |
|---|
| 概念关系（对比、层级） | 白板/画板 | 章节标题下方第一位置 |
| 流程步骤 | 编号列表 | 正文中 |
| 数据对比 | 表格 | 表格上方一句话说清结论 |
结构模板
# 文档标题（一句话说清这是什么）
在学 X 之前，先花 Y 分钟搞清楚 Z。（降低阅读门槛的承诺）
## 第一章：是什么（认知层）
→ 核心定义（加粗锚点句）
→ 类比（一个能记住的比喻）
→ 能/不能做什么（表格或对比）
## 第二章：为什么要注意（风险层）
→ 场景复现（让读者"被吓到"）
→ 来源解释（简短，3 句以内）
→ 规避方法（可执行的步骤）
## 第三章：怎么用（行动层）
→ 反例/正例对比（让读者看到自己的错误）
→ 可直接复用的模板或句式
→ 一句话总结行动要点
结构原则： 认知 → 风险 → 行动，顺序不能倒。每一层只解决一个问题。
扩展参考
