写完只是第一版
技术文章最容易出现的问题,不是作者不懂,而是作者太懂了。
因为太熟悉主题,很多上下文会被自动省略:
- 为什么要学这个?
- 读者现在卡在哪里?
- 这个概念和另一个概念有什么区别?
- 示例能不能跑?
- 结论有没有前提?
- 读完以后能做什么?
所以文章写完后,最好不要马上发布。把它当成第一版草稿,用一套清单复盘,质量会稳定很多。
先确认读者和目标
发布前先问:
这篇文章写给谁?
读者读完以后应该能做什么?如果回答是“写给所有人”,通常等于没有目标读者。
更具体的写法:
- 写给刚接触 Vue 3 的前端开发
- 写给已经会用 MySQL,但不太会看 EXPLAIN 的后端开发
- 写给能写 prompt,但想把提示词优化流程工程化的人
- 写给刚买云服务器,不知道怎么排查线上问题的个人站长
目标越清楚,取舍越容易。你会知道哪些基础要补,哪些细节可以跳过。
检查标题是否承诺过大
技术文章标题最忌讳“看起来很大,实际很散”。
例如:
彻底掌握 JavaScript这个标题几乎不可能被一篇文章兑现。
更好的标题:
JS 作用域与作用域链:为什么函数看到的是定义时的变量好标题通常满足:
- 主题明确
- 范围可控
- 能看出读者收益
- 不用过度夸张词
如果标题写了“实战”,正文就应该有真实步骤或案例。
如果标题写了“避坑”,正文就应该有具体坑和修复方法。
如果标题写了“入门”,就不要默认读者已经懂一堆前置概念。
检查结构是否能扫读
很多读者不会从头到尾细读,而是先扫标题。
发布前只看 ## 和 ###,问自己:
- 不看正文能不能知道文章脉络?
- 小节顺序是否符合学习路径?
- 有没有两个小节在讲同一件事?
- 有没有突然跳到另一个主题?
一个清晰结构通常像这样:
问题是什么
为什么会这样
核心概念
具体做法
示例
常见坑
总结结构不清时,不要先润色句子。先调大纲。
检查概念有没有落地
技术文章不能只讲抽象概念。
差的写法:
缓存可以提升系统性能,但也会带来一致性问题。这句话没错,但读者很难行动。
更好的写法:
如果文章详情页用了进程内缓存,编辑文章后要考虑缓存失效。否则后台保存成功,前台可能仍然看到旧内容。最小做法是保存成功后删除对应 slug 的缓存;如果是多进程部署,还要接受每个进程缓存短时间不一致,或者改成集中式缓存。落地不是一定要写很多代码,而是要回答:
- 在什么场景下会遇到?
- 会造成什么后果?
- 怎么判断自己有没有这个问题?
- 最小修复方式是什么?
- 更完整的方案是什么?
检查示例是否真实
示例是技术文章的骨架。示例太假,文章就会飘。
发布前检查:
- 代码能不能运行?
- 变量名是否贴近真实业务?
- 输入和输出是否对应?
- 示例是否覆盖边界情况?
- 是否为了简短省略了关键步骤?
坏示例:
function doSomething(data: any) {
return data
}更好的示例:
function normalizeTags(input: unknown): string[] {
if (!Array.isArray(input)) return []
return input
.map((item) => String(item).trim())
.filter(Boolean)
}真实示例不一定复杂,但应该能体现问题。
检查事实和边界
技术文章很容易因为一句绝对化表达出问题。
需要警惕这些说法:
- “一定”
- “永远”
- “所有项目”
- “最佳实践”
- “彻底解决”
很多结论都有前提。比如:
小流量个人博客可以接受进程内缓存。这比下面这句更准确:
缓存就应该放内存里。如果内容涉及版本、框架行为、厂商能力、线上配置,最好标注适用条件。对于不确定的点,可以写“需自行验证”,不要把猜测写成事实。
检查读者能不能照着做
一篇可执行的文章,通常会给出明确步骤:
1. 先检查...
2. 再运行...
3. 如果看到...
4. 说明...
5. 下一步...不是所有文章都要写成教程,但如果文章目标是解决问题,就应该让读者知道下一步怎么做。
可以在每个大节后加一个小结:
- 怎么判断
- 怎么处理
- 常见误区
这样读者即使只扫读,也能拿走方法。
检查有没有重复和废话
技术文章要给读者留耐心。
常见冗余:
- 同一个概念用三种说法重复解释
- 每节开头都写“这个很重要”
- 大段背景没有进入主题
- 结尾总结只是重复标题
删文比写文难,但很值得。
一个简单办法是:每段问一句“这段删掉,读者会少知道什么?” 如果答案不明显,可以删或合并。
发布前 8 条清单
- 标题是否准确表达文章范围?
- 首段是否说明读者能获得什么?
- 小节标题是否能单独构成文章大纲?
- 每个核心概念是否有场景或示例?
- 代码和命令是否能运行或已说明前提?
- 结论是否写清适用边界?
- 是否避免裸 URL、重复 H1 和过长段落?
- 总结是否给出可带走的方法或清单?
总结
技术写作不是把知道的东西倒出来,而是帮读者建立一条可走的路。
写第一版时可以尽量展开,复盘时要替读者做取舍:删掉噪声,补上前提,把抽象概念落到例子里,把经验变成步骤。
文章越清楚,读者越容易相信你;文章越可执行,读者越愿意回来。
下次见。
-EOF-