doc-standard

name	doc-standard
description	好文档写作与评审标准。用于：写作新文档、审查现有文档质量、修改文档内容、排版优化、添加 callout/图示。 触发场景：用户提到"写文档"、"审查文档"、"文档标准"、"好文档"、"排版"、"callout"、"文档质量"、"写作规范"时自动触发。 适用所有飞书文档和 Markdown 文档的创建与编辑。

好文档标准 v1.0

一句话锚点

好文档 = 让读者"记住并愿意用"，而不是"看完觉得全面"。

每一个写作选择——结构、措辞、配图、排版——都必须回答同一个问题：这一步，是帮读者记住，还是只是让文档看起来更完整？

---

核心五原则速查

#	原则	一句话	判断标准
1	先锚后展	每节第一句必须是核心结论，加粗钉住	只看第一句就离开，是否拿到了最重要的东西？
2	类比优先于列表	"一次理解"用类比，"反复翻阅"用表格	读者合上文档，能回忆起哪个画面/比喻？
3	场景复现优于罗列	讲风险先还原真实场景，让读者"被吓到"	读者脑中是否"播放"了一个画面？
4	用对比驱动改变	教学内容用 ❌反例 / ✅正例 对比呈现	读者是否意识到"我之前是错的"？
5	语气像人讲话	有停顿、有强调、有吐槽，朗读不别扭	听起来像"有人在跟我聊"还是"念说明书"？

---

快速执行指南

写作时

1. 每个章节：先写加粗锚点句 → 再展开
2. 讲概念：先给类比（一句话能记住的比喻），再列要点
3. 讲风险：先复现场景（"它会一本正经地给你列 5 条引用，你去查，2 篇不存在"），再讲来源
4. 教方法：❌反例 / ✅正例 相邻出现，形成视觉对比
5. 结尾：不要硬加总结框架——如果文章本身够好，读者自然知道该怎么做

审查时

逐条过「发布前检查清单」（详见 references/checklist.md），任何一条不通过就回去改：

• 锚点测试：只看每节加粗句，核心信息是否完整？
• 记忆测试：合上文档，能回忆起什么？
• 动机测试：读者是否意识到"我之前做错了"？
• 语气测试：朗读出来，像人说话还是机器输出？
• 冗余测试：有没有只让文档"看起来更完整"但没帮读者记住任何东西的段落？删掉它。
• 视觉测试：反例/正例相邻？callout ≤ 2 个/章？红色强调 ≤ 5 处？
• 脱节测试：最后一段和第一段是否在同一场对话里？

---

视觉规范速查

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 句以内）
  → 规避方法（可执行的步骤）

## 第三章：怎么用（行动层）
  → 反例/正例对比（让读者看到自己的错误）
  → 可直接复用的模板或句式
  → 一句话总结行动要点

结构原则： 认知 → 风险 → 行动，顺序不能倒。每一层只解决一个问题。

---

扩展参考

• 完整五原则详解：references/principles.md
• 发布前检查清单：references/checklist.md
• 飞书文档 XML 格式参考：参见 lark-doc Skill 的 references/lark-doc-xml.md