69 lines
6.0 KiB
Markdown
69 lines
6.0 KiB
Markdown
# 飞书文档写作原则
|
||
|
||
写飞书文档，像一个该领域资深的人类作者那样写，而不是把内容"装配"成组件。
|
||
本文只讲"何时用、什么风格"；具体标签 / 命令语法见 [`lark-doc-xml.md`](../lark-doc-xml.md)。
|
||
|
||
## 一、用户明确要求优先
|
||
|
||
用户点名要某种格式——高亮块、分栏、列表、某编号体例、表格、画板、某模板、某已有文档的风格——**一律照用户的来，下面的"默认克制"全部让位**。用户给了样例或已有文档，就沿用它的结构与语气。
|
||
|
||
## 二、默认写连贯段落
|
||
|
||
用户没指定时，**默认是连贯段落**；其余按内容类型分流，别一律"少用结构"，也别什么都升标题：
|
||
|
||
| 内容 | 用什么 | ❌ 别 |
|
||
|---|---|---|
|
||
| 叙述、论证、分析、说明 | **连贯段落** | 拆成列举 |
|
||
| 真·行列数据（预算、指标、对比、排期、字段说明） | **表格** | 写成段落或把字段堆成一行 |
|
||
| 字段:值（主题、时长、负责人等，少量） | **加粗标签行**或一句话 | 每字段一个标题 |
|
||
| 方法 / 措施 + 每项一段描述 | **加粗引导句段落**（「**全程督导。**…」） | 每项升标题 |
|
||
| 任务清单 / 检查项 / 待办事项 | **`<checkbox>`** | 用普通列表替代可交互待办 |
|
||
| 纯短并列项（无描述，如材料清单） | 列表 | — |
|
||
| 章节（内容成块、需在目录导航） | 标题层级 | — |
|
||
|
||
- 判断标准：**去掉结构后能顺成段落，就用段落；成行成列的数据，就用表格。**
|
||
- **红线一：标题层级只给"章节"。** "小标题 + 一两句话"的小项（字段、方法、要点）不该占标题层级——按上表降成标签行 / 加粗引导句段落（否则目录里全是没信息量的条目）。
|
||
- **红线二：列举（「一是 / 二是」「第一 / 第二」「(1)(2)(3)」）只给真正并列的具体项，且别每节都用。**
|
||
- 「一是 / 二是」是党务列举的措辞——只用在列具体的**问题 / 措施**那一处；背景、现状、认识、分析、过渡、总结**一律成段**。
|
||
- **整篇每段 / 每节都"一是 / 二是"，和"每段一个 bullet"是同一个骨架化的错——不因为是党务就变对**（纯清单 / 台账类除外）。
|
||
|
||
## 三、按体裁写
|
||
|
||
- **公文 / 法律 / 学术 / 申报 / 项目方案等严肃正式提交物**：靠规范的标题层级、段落与编号体系表达；**默认不用高亮块、分栏**，要强调用加粗或规范小标题。
|
||
- **面向公众号、微信等外部平台粘贴 / 发布的内容**：不用飞书特有富 block（高亮块、分栏等），粘出去会丢样式 / 错乱；改用标准标题、段落、列表、引用。
|
||
- **一般文档**：以可读为先，不堆砌结构。
|
||
|
||
## 四、编号与层级
|
||
|
||
- **一套编号体例、全篇一致；最忌中文大层级与阿拉伯小数编号混用。**
|
||
- 公文 / 正式材料常用：「一、→（一）→ 1.→（1）」（中文大层级 + 阿拉伯细分层级）。
|
||
- 学术 / 技术 / 商业报告：「1 → 1.1 → 1.1.1」或「一、→（一）→ 1.」，**择一**。
|
||
- ⚠️ **「一、」只能配「（一）」；要用阿拉伯小数就从顶层全用「1 / 1.1」。绝不「一、」配「1.1 / 2.1」**——这是最常见的混用。
|
||
- **不混用**多套（别"第X部分"+"一、"+"1."混着来）；**同级不跳号**；**不跳级**。
|
||
- **编号 / 标题层级只给"章节"**，不要为了凑齐体例把每个小项都编上「（一）」、升成标题（小项处理方式见上文「二、默认写连贯段落」）。
|
||
- 简单的 1.2.3 并列项用原生 `<ol><li seq="auto">…</li></ol>` 让飞书自动编号、自动对齐；「一、(一)」原生产不出，才手打成文字——此时用标题级别表达层次，**不靠手动缩进**、各级顶格（全角括号「（）」叠手动缩进会视觉错位）。
|
||
|
||
## 五、飞书特有组件，克制使用
|
||
|
||
- **高亮块 `<callout>`**：很重的强提醒信号，**默认不用**；只给"不提醒就会出错 / 遗漏"的关键项，全文极少（0~1 个），不要每节导语 / 结论都做成高亮块。
|
||
- **分栏 `<grid>`**：仅左右信息量相当、确需并排对照的短内容；否则用段落或表格。
|
||
- **画板**：默认用文字，只在**图示明显比文字更易懂**（流程、架构、时间线、对比、占比等）或用户要求时才用。怎么插、用哪种类型见 [`lark-doc-xml.md`](../lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](../lark-doc-whiteboard.md)。
|
||
- **颜色**：默认朴素、不上色；需要时保持语义一致，按下表选择对应颜色，不为装饰上色。可用色见 [`lark-doc-xml.md`](../lark-doc-xml.md) 的「美化系统」。
|
||
|
||
| 语义 | 背景色 | 文字色 |
|
||
|-|-|-|
|
||
| 信息、说明 | `light-blue` | `blue` |
|
||
| 成功、推荐 | `light-green` | `green` |
|
||
| 警告 / 错误 / 风险 | `light-red` | `red` |
|
||
| 注意、待确认 | `light-yellow` | `yellow` |
|
||
| 中性、辅助 | `light-gray` | — |
|
||
|
||
## 六、写完自检
|
||
|
||
交付前快速回看：
|
||
- **叙述是否被列举化**：背景 / 现状 / 认识 / 分析 / 成效 / 过渡 / 总结等应成段；列举只用于同层级、可并列处理的信息，如问题、措施、步骤、任务或材料清单。若正文反复使用连续编号、项目符号或固定并列句式，导致内容缺少叙述，应把背景 / 认识 / 分析 / 过渡改写成有承接关系的段落（纯清单 / 台账类除外）。
|
||
- **数据是否正确呈现**：成行成列的数据应使用表格呈现，不要写成段落，也不要用分隔符把多个字段硬串在一起。
|
||
- **标题是否滥用**："小标题 + 一句话"的小项不要升成标题；应改成标签行、加粗引导句段落或普通段落。
|
||
- **编号是否统一**：全篇一套、不跳号、不跳级，尤其不要中文 + 阿拉伯混用（如「一、」配「1.1」）。
|
||
- **组件是否克制且保真**：高亮块 / 分栏 / 画板 / 颜色应符合体裁和用户要求；引用 / 图片 / 资源块必须保留。
|