技术写作与文档2009jacobian.org编辑精选
如何写出好文档：你需要一位编辑
Writing great documentation: you need an editor
导读
这篇短文讲的是：写好文档的关键一环是找一位编辑（或至少用编辑的视角）来审读你的文字，作者给了若干可操作的方法。对写作者的价值在于，它把“自己改自己的稿”这件难事拆成了具体技巧——换排版、换呈现方式，制造心理距离，从而更客观地删改。
可以直接用的写作要点
- 01
写完初稿后，把“写作”和“审稿”分成两个阶段、两个角色，别在同一次坐下里既写又改。
- 02
换掉文字的外观（改页边距、换字体、换成排版后的 PDF）能让你对自己的稿子产生陌生感，从而更狠得下心删改。
- 03
为自己准备一份风格指南（如《经济学人》风格指南），把格式、用词、标点上的琐碎决定交给规则，省下精力打磨内容。
- 04
把稿子当作别人的文章来读：先只提问题、不下判断，再逐条回应。
HN 评论精选
用成熟的风格指南来统一文字规范，省去反复纠结。
我推荐《经济学人》风格指南。我那些做纸媒记者的朋友对它评价很高。指南有一个精简版小册子，可以离线查阅。这本指南基于发给《经济学人》所有记者的风格手册。
tezza查看英文原文
I recommend the Economist Style Guide. My friends who are print journalists regard it highly. A slim novella of the guide is available for offline reference. "This guide is based on the style book which is given to all journalists at The Economist." http://www.economist.com/research/styleguide/
改变版式能制造心理距离，让自我审稿更客观。
“改掉页边距”是审读自己文字的一个窍门。作者说，这样能让人更容易做到不带个人感情地看待自己的稿子。我好奇，换个高亮配色方案是不是也能帮自己审代码？
wisty查看英文原文
"Change your margins" is one trick for reviewing your own text. The author says it makes it easier to be impersonal. I wonder if changing your highlighting scheme would help you review your own code?
把文字排成与写作时完全不同的形态，能显著提升自我审稿时的抽离感。
我最喜欢的自我编辑技巧是“改页边距”的加强版。我的写作出版流程里包含排版，所以即使最终不用，我也会先把文字排成 LaTeX 再在那上面改。宽页边距加上与等宽文本编辑器完全不同的呈现方式，让抽离出来变得容易得多。
tel查看英文原文
My favorite trick for self editing is an extension on the "change your margins" trick. My print writing/publishing cycle involves typesetting, so even if it's not going to be used for my final target I typeset things in LaTeX and then edit them there. Wide margins and a totally different presentation from my monospaced text editor makes detachment much, much easier.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选