技术写作的目标不是把所有细节都写进文章,而是让读者能快速重建判断过程。
先写问题
先说明你在解决什么问题,再说明方案。很多笔记难读,是因为一开始就进入实现细节,读者不知道这些细节为什么重要。
记录约束
方案往往只在特定约束下成立。记录约束可以避免未来误用:
- 运行环境
- 数据规模
- 安全要求
- 维护成本
保留取舍
如果你选择了 A 而不是 B,最好写下理由。未来重新评估时,这比结论本身更有价值。
export function usefulNote(problem, constraints, decision) {
return { problem, constraints, decision };
}
保持可更新
一篇技术笔记应该能被后续经验修正。静态博客并不妨碍更新,Markdown 反而让修改成本更低。