技术写作与文档2014shubhro.com编辑精选
软件工程师应该写作
Software engineers should write
导读
这篇短文主张软件工程师也应该写作，因为写作能逼你把问题想清楚，也是与代码同样重要的表达与思考训练。对写作者来说，它提供了跨领域的视角：不必等有读者才动笔，持续写作和反复修改本身就会带来认知与表达上的回报。
可以直接用的写作要点
- 01
把写作当成理解测试：如果你不能用简单的话解释一个概念，就说明还没真正弄懂它。
- 02
坚持日常写作，即使读者为零也有价值；可以用私人博客或第二语言写作来降低压力、练习表达。
- 03
修改文章时像优化代码一样反复删冗余、合并相似观点、澄清论点，清晰和优雅是共同标准。
- 04
把编程、写歌等都看作不同媒介的写作，核心都是组织想法并用合适形式表达。
HN 评论精选
每日私人写作即使没有读者也能影响自己，还可以用外语写作来练习。
“即使没人读你的文章，写它也会对你产生影响。”自从读了 HN 上一篇《为什么你应该每天写作》后，我每天在私人博客写作，用英语来提升第二语言（母语是葡萄牙语）。我从 2014 年 9 月 22 日开始，尽量写自己的想法，因为相信这是正确的事，也是提升自己的最好主题。这不容易，我还没觉得自己在进步，但内心觉得应该坚持。
edpichler查看英文原文
"Even if nobody reads your essay, writing it will make an impact on you." After reading a post in HN (https://news.ycombinator.com/item?id=5614689) entitled "why you should write every day", I've being doing it daily in a private blog. I do it in English to improve my second language. My main language is Portuguese. I'm doing it since 09/22/2014. I try to write about my own ideas, because I believe is the right thing to do and it is the best subject to improve myself. It's not an easy task, and I do not feel I'm improving yet, but something in me tell me that I should keep doing it.
写作是检验自己是否真正理解、能否简单解释的测试。
我一直喜欢爱因斯坦那句话：“如果你不能简单地解释它，说明你理解得还不够好。”写一个主题，是检验你能否简单解释它的好方法。
kalid查看英文原文
I've always been a fan of Einstein's quote "If you can't explain it simply, you don't understand it well enough." Writing about a topic is a good test of whether you can explain it simply.
编程可视为另一种媒介的写作；有效的解释和教学需要具体示范，而非死记硬背。
我一直是“英语孩子”，中学数学差点不及格，高中代数 I 挂科重修；同时在上高级编程课，十年级最后学期准备 AP 计算机科学。回头看，这段经历让我明白示范对教学有多重要。我的代数老师不能为我示范问题，从不解释，只要求背；没有真实具体的例子（人为应用题不算），只是考试。我的高中数学经历像美国 STEM 教育问题的速成课。在我看来，编程一直是写作的一种形式，就像写歌是写作的一种形式，只是媒介不同，结果不同。
tomphoolery查看英文原文
I was always an "English kid", came close to failing my math subjects in middle school and finally in high school, I did fail Algebra I, and had to re-take it the next year. Meanwhile, I was in advanced programming courses and on my way to take an AP Computer Science course in the last semester of my sophomore year. Looking back, that experience taught me about how important modeling is to pedagogy. The fact is, my Algebra I teacher couldn't model the problem for me. He never explained anything, just expected us to memorize everything. We were never given real, tangible examples (contrived word problems don't count and never did!)...all we did was take stupid tests. My high school math experience was like a crash course in everything that's wrong with STEM education in America, and why we need to alter that if we're going to depend more on STEM in the real world. In my opinion, programming has always been a form of writing. Just like songwriting is a form of writing. It's simply a different medium, and therefore you get a different result. I might be looking at it from a different kind of lens though.
清晰思考是编程与写作的共通核心，反复修改文本如同优化代码。
完全同意。作为花大量时间学习人文、艺术等需要持续写作（资助申请、论文等）的开发者，我发现做好开发者的许多技能对写论文极有价值，反之亦然。两个领域的核心技能都是清晰思考。最好的软件工程师也是好作者，因为他们的文字和代码一样有逻辑、优雅。我个人发现反复梳理文本、删多余词、合并相似观点、澄清论点差别巨大，很像优化软件；其他学生通常不这样做，写作因此受损。
euphemize查看英文原文
Thoroughly agreed. As a developer who spent a lot of time studying humanities, arts and other disciplines requiring constant writing for grant submissions, essays, etc. a lot of skills required to be a good developer become invaluable for a dissertation and the other way around. > A core skill in both disciplines is an ability to think clearly. The best software engineers are great writers because their prose is as logical and elegant as their code. Personally, I found that combing through my text again and again and again to cut down on unnecessary words, combining similar ideas ideas and clarifying points made a huge difference, and was very much akin to optimizing software. It was generally something other students didn't really bother to do and their writing greatly suffered from it.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选