技术写作与文档2019arturdryomov.dev编辑精选
论技术写作
On Technical Writing
导读
这篇文章记录作者自己从零开始写技术博客、给自己定下「每月一篇」目标的经历与心得。值得写作者一读，是因为它触到一个常被混淆的问题：职业意义上的「技术文档写作」和「写关于技术的文章」是两套不同的规范；而无论写哪种，真正的起点都是持续动笔，而不是先去折腾博客工具。
可以直接用的写作要点
- 01
先分清自己写的是「技术文档」还是「关于技术的文章」：前者目标是准确、可执行、出错有代价，后者允许观点与自由发挥，别把两套标准混着用。
- 02
起步阶段别被域名、主题、自建托管这些技术细节绊住，先开个免费博客写起来，内容优先于形式。
- 03
同一个概念用几种不同方式各讲一遍——读者卡壳、追问的地方，就是你需要展开解释的地方。
- 04
设定每月一篇这类可执行的节奏，但同时要补基本功：时态统一、少用缩写、句子干净，别让语法问题分散读者对观点的注意力。
HN 评论精选
区分「技术文档写作」与「写关于技术的文章」，两者规范与容错度完全不同。
这篇文章和许多讲「技术写作」的文章一样，把技术写作和写关于技术的文章混为一谈了。在我看来这是两回事。技术写作是一门职业，有大量成熟规范、相对明确的目标和很长的历史，它和斯蒂芬·金、《风格的要素》几乎没什么关系——那些当然可以用，但专业的技术写作从业者会推荐技术传播的教科书、论文或同行的博客。技术写作还有严肃的后果：导弹手册出错，可能损失数千美元甚至数千条人命，斯蒂芬·金的建议在这种场合帮不上什么忙。作者真正在做的是「写关于技术」，大多数技术博客也更接近这一类：更自由、更随性、充满观点和可能方案的暗示，而不是固化的流程文档。这个区分也许显得学究气，但我希望更多人尊重它——这篇文章有点标题党，我本以为它讲的是职业意义上的技术写作（写文档）。
voidhorse查看英文原文
This article, like many on “technical writing” conflates techincal writing and writing about technology. In my estimation, they’re two different things. Technical Writing is a profession with a massive set of practices, relatively well-prescribed goals, and a long history. It’s a discipline that has almost nothing to do with Stephen King and Strunk and White—though of course these sources might be applied. Chances are, if you were to ask an professional technical writer about resources for technical writing, they’d point you to a few text books on technical communication or papers or blog posts from people in the industry. Technical writing also has serious consequences. If a manual for a missile has mistakes, it could cost thousands of dollars or thousands of lives. Stephen King’s advice isn’t quite as helpful in such perilous situations. Writing about technology, I think, is closer to what the author is actually pursuing here—and most tech blogs better fit this classification than technical writing. Writing about technology is more free form, more whimsical, full of opinion, intimations of possible approaches or solutions but not hardened proceedural documentation. It might seem a bit pedantic to make such a distinction, but I would really love it if more people honored it. For instance, this article was a bit of false advertising, since I thought it’d be about technical writing in the professional sense (i.e. writing documentation) and not about writing about technology in a more casual, opinionated way. It’s similar to the distinction between programming and software engineering—they’re quite distinct pusuits, even though the tools and techniques considered overlap.
别纠结形式直接开写，靠多年持续写作和「换几种方式重讲」来打磨表达。
这篇文章其实挺空的：开头像是要讲如何写出好的技术内容，接着变成了自传，然后变成怎么开始写博客，最后用一些大概没人关心的统计数字草草收尾。如果你想知道怎么写得更好，斯蒂芬·金的《写作这回事》挺有意思、读起来像小说，可以当作「读完就有动力去写」的书。如果你想进入博客写作：直接开始就行，弄个 WordPress 然后写，专注内容而不是形式，域名、自定义主题、用 Hugo 自建托管这些以后再说。如果你想成为好的技术写作者：持续写，多年不间断的写作才会让你变好。对我来说最有效的技巧是拿自己的想法去做一次互动演讲，看听众在哪里卡住、问什么问题、哪种解释方式能讲通。马尔科姆·格拉德威尔做得更多：他会用不同方式把一个观点解释好几遍。如果你有篇幅，就这么做——不同的人需要不同的解释方式。
baby查看英文原文
This article is actually quite empty, it starts like it is going to be about how to write good technical content, then becomes an auto-biography, then becomes an article on how one can get started blogging, then just end abruptly with some statistics that probably nobody cares. So if you came here to know how to write, Stephen King wrote a book "On Writing" that is quite interesting and mostly reads like a novel. See it as a "I'll read this and I'll get motivated to write". If you came here to understand how to get into blogging: just start. Create a wordpress, and just start writing. Focus on content, not on form. After a while, you can think about a domain name, about a custom theme, or about hosting this yourself on github with hugo. But don't start with the technical parts of managing a blog, just write. If you came here to understand how you can become a good technical writer: keep writing. Consistence over years of writing is what makes you a good writer. The ultimate technique for me is to give an interactive talk to people about your ideas, and see where your audience get stuck, where they ask questions, how different ways of explaining something get the point across. Malcolm Gladwell does more than this: he explains an idea multiple times in different ways. If you have the page count to do this, do it. Different people need different ways of explaining. (shameless plug: I'm writing a book on crypto https://www.manning.com/books/real-world-cryptography?a_aid=Realworldcrypto&a_bid=ad500e09)
逐句改稿示范：时态要统一、缩写慎用、模糊短语要换成具体说法。
一个自称热爱阅读的人写得这么差，我很意外。比如这句「Fast-forward to the last year of school. I've started writing. It was nothing special really, short fictional stories there and there.」时态混乱，我也看不懂「there and there」是什么意思。更好的写法是：「Fast-forward to my last year of school. I started writing. It was nothing special really, just some short stories.」文中还有几处该用「I」却用了「I've」，我建议这位作者干脆避免这类缩写。每月至少写一篇文章的目标值得肯定，但他该先把写作基本功练好，也许《风格的要素》会有帮助，找个老师或教练更好。
herodotus查看英文原文
I am surprised that someone who claims to have been an avid reader writes so poorly. Consider, for example, "Fast-forward to the last year of school. I’ve started writing. It was nothing special really, short fictional stories there and there." The author's tense is muddled, and I have no idea what "there and there" means. Better would be "Fast-forward to my last year of school. I started writing. It was nothing special really, just some short stories." There were a few instances where the author should have used "I" rather than "I've". In fact, I would encourage this author to avoid such contractions altogether. The goal of writing at least one article a month is laudable, but this author should work on writing craft fundamentals. Perhaps a book like The Elements of Style would help. Even better would be a tutor or coach.
为了修辞效果而下的绝对化断言容易被读者抓住，写作时别夸大因果。
原文说「当然那时没有推荐引擎，所以我把一切都读了个遍，渴望吸收人类留下的经验。听起来像上瘾吧？确实有点像。」但那时其实是有类似机制的。我不认为你会纯靠偶然读到《霍比特人》《三个火枪手》和《福尔摩斯》。认为「最好的内容浮到大众意识表层只是现代机器学习推荐引擎的产物」，这种说法站不住脚。
kristianc查看英文原文
> There were no recommendation engines of course so I went through everything, itching to consume experiences left behind by humanity. Sounds like an addiction, right? Well, it kinda was. Well, there kind of were. I doubt you would end up reading The Hobbit, The Three Musketeers and Sherlock Holmes purely by accident. The idea that the best content bubbling to the top of the popular consciousness is merely a product of modern ML recommendation engines is for the birds.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选