技术写作与文档2022heinrichhartmann.com编辑精选
写给工程师的写作课
Writing for Engineers
导读
这篇是写给工程师的写作指南：随着职级提升，表达能力的欠缺会成为影响力的瓶颈，作者给出了一套可操作的写作方法。对写作者而言，它把“写清楚”拆成了可练习的具体动作（明确主旨、面向读者、先写再改），尤其适合技术背景的人把写作当作工程问题来处理。
可以直接用的写作要点
- 01
动笔前先写一句话点明“这篇的要点是什么”，全文围绕它展开，删掉不服务它的内容。
- 02
先确定读者是谁、需要什么层次的细节：对非技术读者给结论和要点，别把实现细节全倒出来。
- 03
用你说话时会用的句式和词，不要为了显得聪明而堆术语和复杂句。
- 04
不要从空白页开始：先列要点、写粗糙草稿，再分享给别人看、反复改写。
- 05
发布前务必校对，一个错字就会削弱整篇文章的可信度。
HN 评论精选
有工程师坦白写作既难又无趣，说明写作要先降低门槛、直接呈现价值，别把它变成额外负担。
认同资深工程师需要更强表达能力，但忍不住想：为什么非得这样。写作对我而言很难也不好玩，搭系统难但有趣，我只想把大部分时间花在后者上。我不在乎“影响力”，也不想说服别人接受我的想法——你做出个酷东西给我看一点，我喜欢就愿意放下一切来一起做；有想法就去动手试，撞到约束再说，失败也是乐趣。我不是为了当好作家才当工程师的。
pm90查看英文原文
I agree with this perspective of the world (that senior+ software engineers need to be able to express themselves more fluently to be able to be impactful) but… just as a thought experiment, I wish it didn’t have to be that way. Writing is hard and not much fun (to me). Building systems that do something is hard but its a lot of fun. I just want to spend most of my time doing the latter. I just don’t give a fuck about impact or convincing others to work on my idea. If you are building something cool, show a little bit of it to me, and I like what I see, I would love to be able to drop everything else and work with you to complete it. Or if I think of some automation to reduce toil, I just wanna go tinker without having to think it through too much. If I run into constraints when building it, so be it, its a learning experience, but even failing is fun. Obviously a rant. I just didn’t become a software engineer to be a good writer. I always wanted to build first and learn the constraints through mucking around rather than giving it so much thought before a single line of code is written.
面对非技术听众，要给要点摘要而不是细节堆砌。
“了解你的读者”这点在会议里特别明显：有些同事对着非工程背景的人长篇大论地解释概念和问题，我有时会私信提醒他们——对方不需要那些细节，他们要的是关键要点的摘要，但这种提醒并不总被接受。
alimov查看英文原文
> Know your audience This point is something that I notice in a lot of meetings. Some of the engineers I work with are long winded and tend to over-explain concepts/issues to non-engineering folks. I try to send a direct message during the meeting (now and then) to try and reel them in a little by explaining that the non-engineering folks don’t need those details and that a what they are really asking for is a summary of the key points of the concept/issue under discussion, but it’s not always well received.
十条可复用的清晰写作清单：定要点、像说话一样写、别装聪明、早分享、知止。
这篇文章的建议很好，英国政府数字服务团队那份“清晰写作十条”也很实用，部分观点重合且有补充：1）先确定“要点”；2）像说话那样写；3）别试图显得聪明；4）把东西展示出来；5）记住你和你的文字不是一回事；6）把作品分享出去；7）多读，尤其是诗；8）永远不要从空白页开始；9）知道何时该停；10）保持人味。
open-source-ux查看英文原文
Lots of good advice in this post. I also find the 10 tips for clear writing at the following link very helpful - it overlaps with some of the advice in the post above - and includes some additional suggestions: https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/ You don't need to listen to the podcast at the top of the page above (unless you want to). Instead, scroll down the page and you'll find a short description of each of the following tips. 1. Establish ‘The Point’ 2. Write it like you’d say it 3. Don’t try to sound clever 4. Show the thing 5. Know that you are not your writing 6. Share your work 7. Read (poetry in particular) 8. Never start with a blank page 9. Know when enough is enough 10. Stay human
细节校对和格式使用同样影响可信度：错字与滥用引用块都会让读者分心。
文章里出现“your are not ready”这样的错字挺讽刺的——讲“如何写好”的文章里犯低级错误总是更好笑一点。另外我觉得文中那些引用块很分散注意力：它们到底在引用谁？看起来更像插入的旁注而非真正的引文。
madeofpalk查看英文原文
> your are not ready heh. Ironic. Everyone makes silly mistakes. Just mildly funnier when it happens in an article about "how to writes good" While we're on topic of annoying besides-the-point HN pedantry, I find the use of blockquotes in this article to be distracting. What are they quoting? They seem to be more of an aside than an actual quote?
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选