大家好，我是程序员柏风，AI 最全的 Vibecoding 学习地图 http://coderoadmap.cn 作者。
写作结构与风格
同样准确的内容，结构差 会让读者放弃；风格乱 会让品牌失去信任。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 保准确。 下一课从用户研究与选题找文档缺口。