技术写作与文档2020philipkiely.com编辑精选
Show HN：写给软件开发者的写作书
Show HN: Writing for Software Developers
导读
这是 Philip Kiely 为自己的新书《Writing for Software Developers》做的发布帖，书里既有写作方法，也收录了对 11 位技术写作者的访谈。评论区围绕“为什么写、写什么、写完怎么推广”展开了对写作者很实用的讨论：写作是逼自己想清楚的过程，也是职业发展的杠杆，而选题应回到自己真正在意的问题上。
可以直接用的写作要点
- 01
写自己真正想探索、想搞懂的问题，写作本身就是逼自己把思路想透的过程，不必为了流量去写不感兴趣的题目。
- 02
不要在选题上反复纠结：先写、经常写，把读者反馈吸收进下一版，像重构代码一样反复修改。
- 03
把写作当成职业资产来经营，一篇讲清楚问题的文章可能直接带来工作、合作者和行业影响力。
- 04
写完还要考虑分发：技术社区、付费出版方名单等渠道，值得在动笔前就想好。
HN 评论精选
写自己真正想探索的题目，写作本身就是逼自己想清楚的过程，不必为流量写不感兴趣的题材。
总有人说“靠写作打造个人品牌”，也总有人说“团队里用文字沟通和写代码一样重要”。但再往上走一层：写你个人想探索的想法（就像 pg 那样），正是逼自己把这些想法想透的方式，它本身就有价值，不管有没有人读、有没有人给你点赞。所以写，而且要经常写，不要在挑选题上花太多时间；只管写，把反馈吸收进作品，像反复重构代码那样反复修改。也别因为“如何在托管 K8s 里用 XML 配置 Flibbitz”这类文章能多拿赞，就去写你不感兴趣的东西——除非 Flibbitz 真的让你着迷。写那些让你脑子发痒的东西，并且坚持不懈；我写文章和书取得的那点成绩，都能追溯到写自己真正在意的东西。
braythwayt查看英文原文
Something, something, “Build your brand by writing.” Something, something, “Communicating with words is as important as communicating with code in a team setting.” But moving up Maslow’s Hierarchy, writing about ideas you want to personally explore (a’la pg) is exactly how you force yourself to think those ideas through. It’s valuable in its own right, whether people read them and shower you with the “three Ps” or not. So write, and write often. Do not spend great amounts of time carefully choosing what yo write. Just write, and incorporate feedback into your work. Revise endlessly, much as one refactors software endlessly. Do not write about things that don’t interest you just because you get more up-boats for “How to use Flibbitz in a managed K8s container with XML configuration,” unless Flibbitz personally interests you. Write about what tickles your brain, and keep at it incessantly. What little (and it’s not much in the scale of things) success I’ve had writing essays and books can all be traced back to writing about things I personally care about.
写作是职业发展的高杠杆行为，一篇文章可能直接带来机会；同时提出技术视频与文字在吸引力上的差异。
写作大概是专业人士能做的最有价值的一件事，其他领域也一样。我认识有人因为一篇爆火的 Medium 文章被录用，还成了行业里的参照人物。你怎么看视频？我看到开发者生活方式类频道在起飞，但更技术性的频道有没有机会？我觉得技术视频（演讲、教程）比文章吸引人得多，但恐怕我是少数派。
chpmrc查看英文原文
Writing seems to be the single best thing you can do as a professional, in other areas as well. I know people who were hired because of a single Medium article that got a lot of traction (and made that person sort of a reference in the industry). What do you think about videos? I see lifestyle channels for devs and tech workers taking off but do you think there's a chance the same might happen for more technical channels as well? I find technical videos (like talks or tutorials) to be far more engaging than articles but I'm afraid I'm part of a very small minority.
肯定选题并分享“付费技术写作渠道清单”这一资源，同时关心书中访谈与实操建议的比例。
很高兴看到你把这件事做起来了！你之前提过，我维护的这个仓库（一份为这类技术写作付费的出版方短名单）给了你早期灵感，我还希望六月后多投入技术写作时把这份名单扩充很多。受访名单非常漂亮。我唯一的问题是：这部分在书里处于什么位置？从目录看不太清楚。能否说说访谈和写作建议各占多少比例？
sixhobbits查看英文原文
Hey Philip, really great to see you run with this! I know you mentioned to me that this repository[0] where I try to keep a short list of publishers that pay for this kind of writing was an early inspiration and I'm still hoping to grow that list a lot after June when I spend more time focusing on technical writing too. As others have said, that's a really great looking list of interviewees. My only question is where this actually fits in to the rest of the book? It's not that clear from the Table of Contents. Could you comment on what percentage of the book is interviews, compared to writing advice? [0] https://github.com/sixhobbits/technical-writing/blob/master/write-for-us.md
书中收录 11 位从业者访谈，其中一章专讲作品推广，强调技术社区的分发与人脉价值。
我做了六个月，很高兴终于发布，也赶在（如今变成线上的）大学毕业前六天完成了目标。书里收录了 11 位受访者，包括 Patrick McKenzie。第 15 章讲如何推广作品，他谈到 HN：“我曾是 HN 上排名第二的用户……人们大大低估了 HN，社区里有种说法是 HN 评论区充满戾气、永远在唱衰。我认为 HN unequivocally 是一个在全球范围内创造价值的非凡场所，主要是因为它把原本不会相遇的技术人聚到了一起。有人在那里结下一生的关系；我在那里认识了后来的联合创始人，Thomas Ptacek 是我一生的好友；没有 HN，我大概不会有现在的工作。”
philipkiely查看英文原文
Hi HN, I have been working on Writing for Software Developers for six months and I'm so excited to finally launch it! I set myself the goal of launching before my (now virtual) university graduation and I'm proud to have hit that goal by six days. Right now the book is 12 dollars off (launch pricing) and you can read chapter 1 for free at https://philipkiely.com/assets/files/wfsd_chapter1_sample.pdf The book features interviews with 11 people, including @patio11 (Patrick McKenzie), who had the following to say about Hacker News. This quote is from Chapter 15, which covers promoting your work: "At one point I was the number two user on Hacker News. I might have slipped down to number three...I think that people underrate Hacker News massively. I think there is a meme in the community that Hacker News threads are populated by toxic commenters and that it is a ceaselessly negative place such that the world would be better without Hacker News in it. I think unequivocally Hacker News is an extraordinary venue for value creation throughout the world, largely by bringing together technologists who would not have otherwise met each other. There are people who make lifelong relationships from that site. I met my former co-founders there; Thomas Ptacek is one of my best friends for life; and it feels extremely unlikely that I would have my current job but for Hacker News. I think you could say that for many people who are nowhere close to being quote-unquote on the leaderboard. Hacker News helps disseminate ideas, like my ideas on sales and engineering career optimization and the body of practice that is dealing with venture funding, both from the startup side of the fence and from the investor side of the fence. These things would be difficult to get access to unless you had a high-quality social network that already had an expert about them in it. It is basically one step short of miraculous that you could find George Grellas, who is an expert Silicon Valley lawyer practicing for thirty years, and have George Grellas patiently walk you through the impacts of the changes in the independent contractor classification in the wake of Microsoft abuses in the 1990s. By the way, George Grellas was a practicing lawyer for Microsoft. That I could read that as a person who was newly an independent contractor working in central Japan in the late 2000s/early 2010s is one step short of miraculous. I'll acknowledge that there are certain threads that are generally low quality, mostly things that are removed from the core interests of the technology industry. It's not a particularly great watering hole to talk about politics, for example. But, for the things it does well, Hacker News does them better than plausibly any place in the world...I wish more people who could get value out of Hacker News were active there." Thanks to all eleven people who provided interviews for the book. Thank you for checking out my project! I'll be around to answer any questions.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选