写作结构与风格

同样准确的内容，结构差 会让读者放弃；风格乱 会让品牌失去信任。Style Guide 不是束缚，而是团队写同一产品时的共享默认值。

学习目标

• 掌握技术文档的标题层级与段落节奏
• 理解 CTA、Storytelling 在教程中的克制用法
• 建立 Style Guide 核心条目（语气、术语、格式）

核心概念

可扫描结构

标题 — 承诺本节交付什么
首段 — 谁该读、前提条件、预计耗时
步骤 — 编号、每步一个动作、含期望输出
Recap — 3 条 bullet 回顾
Next — 链到相关 How-to / Reference

一段一意；超过 5 行的段落考虑拆列表或子标题。

标题公式

场景	模式	示例
How-to	如何 + 动词 + 对象	如何创建 REST Track
Reference	名词 + 说明	POST /api/tracks
Concept	什么是 X	什么是 Track Slug

避免 clickbait；技术读者要 准确 > 吸睛。

CTA 与 Storytelling

• CTA：每页 1 个主 CTA（Try it、View API、Open GitHub Issue）
• Storytelling：Tutorial 可用短情境（「你刚接手课程平台…」），Reference 不用
• Before/After：展示改配置前后的 curl 输出，比形容词有力

Style Guide 最小集

人称 — 「你」还是「用户」；全站统一
术语表 — Track、Lesson、Slug 首字母大写规则
代码 — 命令是否含 $ 提示符；占位符用 <YOUR_API_KEY>
 inclusive — 避免 master/slave 等过时用语
中英 — 产品 UI 与文档用语一致

练习

• 把一段 200 字散文改写成编号步骤 + 期望输出
• 为 CodeRoadMap 写 5 条 Style Guide 规则
• 同一 How-to 写两个标题，说明哪个更符合 SEO 与可读性

小结

结构让读者找到答案，风格让读者信任产品；Guide 保一致，Review 保准确。 下一课从用户研究与选题找文档缺口。