归档

技术写作的小型指南

好的技术笔记应该让未来的自己更快恢复上下文,而不是展示当时知道多少。

技术写作的目标不是把所有细节都写进文章,而是让读者能快速重建判断过程。

先写问题

先说明你在解决什么问题,再说明方案。很多笔记难读,是因为一开始就进入实现细节,读者不知道这些细节为什么重要。

记录约束

方案往往只在特定约束下成立。记录约束可以避免未来误用:

  • 运行环境
  • 数据规模
  • 安全要求
  • 维护成本

保留取舍

如果你选择了 A 而不是 B,最好写下理由。未来重新评估时,这比结论本身更有价值。

export function usefulNote(problem, constraints, decision) {
  return { problem, constraints, decision };
}

保持可更新

一篇技术笔记应该能被后续经验修正。静态博客并不妨碍更新,Markdown 反而让修改成本更低。