技术写作与文档

技术写作 是 DevRel 的核心技能：把复杂 API、框架、概念变成 可跟做、可搜索、可维护 的文档。好文档降低支持成本，直接提升 DX。与 /roadmaps/devrel 写作与文档节点对齐。

学习目标

• 区分 Tutorial、How-to、Reference、Explanation 四类文档
• 掌握博客与 API 文档的基本结构与写作原则
• 理解 Sample App 在降低试用门槛中的作用

核心概念

文档四象限（Diátaxis）

类型	读者目标	示例
Tutorial	跟着做，获得成就感	「30 分钟搭建第一个 REST API」
How-to	解决具体问题	「如何配置 JWT 认证」
Reference	查参数、查错误码	API 端点、配置项列表
Explanation	理解原理与权衡	「为什么选择 Spring Security」

新手从 Tutorial 进入；老手常查 Reference。混在一篇里会让两类读者都失望。

博客结构

标题 — 承诺结果（「用 Spring Boot 实现分页查询」）
Hook — 痛点 + 谁适合读
步骤 — 编号清晰，每步有可验证输出
代码 — 完整可运行，注明版本与依赖
收尾 — 下一步链接（文档、Sample、社区）

避免「百科式开头」；开发者打开文章是要 解决问题或完成 Demo。

API 文档要点

• Quickstart：5 分钟内拿到第一个 200 响应
• Authentication：最常见失败原因写在前 3 屏
• Changelog：Breaking Change 醒目标注 + 迁移指南
• 错误码表：含原因、修复建议、示例请求

CodeRoadMap 写 Spring Boot 教程时，版本号与 JDK 要求 必须写在开头，减少环境差异导致的挫败感。

Sample App

• 单一职责：演示一个核心能力，不堆功能
• README 含：前提、安装、运行、预期输出、常见问题
• 与官方文档 双向链接；代码变更时文档同步 PR

练习

• 为一虚构 REST API 写 Quickstart 大纲（≤8 步）
• 将一篇「概念介绍」改写成 Tutorial 开头（含 Hook + 第一步）
• 检查现有文档：Tutorial 与 Reference 是否混在同一页？

小结

文档是产品界面；结构清晰、可运行示例，比辞藻华丽更重要。 下一课进入公开演讲。