技术写作与文档2018news.ycombinator.com编辑精选
Ask HN：对软件开发者有哪些好的写作建议？
Ask HN: What are good writing tips for software developers?
导读
这是 HN 上关于软件开发者日常写作的建议帖，覆盖 PR 描述、同事邮件、提交信息、规格文档和博客文章等场景。讨论核心是简洁、主动语态、删冗余、明确指代，以及先写出来再重组；对需要写技术沟通文字的开发者很有直接借鉴价值。
可以直接用的写作要点
- 01
每天固定写至少 500 词且不受干扰，并读经典写作书，重点练简洁风格和主动语态。
- 02
删掉大多数副词：generally、usually 会削弱观点，very、extremely 容易让文字显得不严肃。
- 03
除非先行词非常明确，否则少用代词；看到 it 就回头检查本句和上一句是否清晰。
- 04
先一口气写出来，再调整句子顺序让每句以重点开头，并狠心删掉那些需要绕弯才能保留的表达。
HN 评论精选
注意常见语法和用词错误，能用简单词就别用花哨词。
以介词结尾句子是很糟的（这句本身就在拿介词结尾开玩笑）。但只有傻瓜才会用 but 开头或结尾，用 and 开头或结尾更是十足的白痴。总之，永远别用 anyway，用 anyways 更糟。能用 use 就别用 utilize。如果 your 和 you're 都分不清，你就写错了。把 to、too、two 搞混的人太多，没必要为此太生气。
DannyB2查看英文原文
A preposition is a very bad word to end a sentence with. But only a fool would begin or end a sentence with the word but. And only a total idiot would begin or end a sentence with the word and. Anyway, you should never use the word 'anyway'. Even worser to use 'anyways'. And never utilize the word 'utilize' when you could utilize the word 'use' instead. Your doing it wrong if you're sentences confuse the words your and you're. There are two many people doing it wrong too get to upset about confusion over to, too and two.
每天定量写作，读经典写作书，坚持简洁和主动语态。
推荐三本书，并开始每天至少 500 词无干扰写作（技术、虚构、意识流均可）：《On Writing Well》《On Writing》《The Elements of Style》。最重要的两点是简洁风格和主动语态；这两个习惯对软件工程师写简洁邮件、规格和提交信息很关键，也会改善 Slack、短信等日常交流。
StriverGuy查看英文原文
I recommend getting three books and to begin writing at least 500 words per day distraction free (technical, fiction, stream of conscious): 1) On Writing Well - William Zinser https://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction-ebook/dp/B0090RVGW0 2) On Writing - Stephen King- https://www.amazon.com/Writing-10th-Anniversary-Memoir-Craft/dp/1439156816/ref=tmm_pap_swatch_0?_encoding=UTF8&qid=&sr= 3) The Elements of Style - Strunk & White - https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X/ref=pd_lpo_sbs_14_img_0?_encoding=UTF8&psc=1&refRID=K0EXMXPXXTNQZ7K2AD0M The two most important points are concise style and active voice. Both of these habits are critical for SEs to write concise emails, specs and commit messages. You will even see improvement in more casual day to day interactions (via slack, SMS etc).
删掉多余副词，代词指代必须明确。
两条我常后悔没遵循的写作反馈：大多数副词是多余的；说 generally 或 usually 往往在削弱自己的观点，而 very、extremely 之类夸张又喘不过气，容易让人觉得你写的东西不严肃。除非先行词明确无误，否则避免用代词；看到 it 就应该立刻重读本句和上一句，检查清晰度。
eropple查看英文原文
The two pieces of writing feedback I've received that I often regret not following: - Most adverbs are superfluous. I am as guilty of ignoring this as anyone, but most cases where you say "generally" or "usually" you're undermining your point and the use of "very", "extremely", etc. are hyperbolic and breathless and make it easier to regard what you're writing as unserious. - Avoid pronouns unless the antecedent is unmistakable. The use of "it" should immediately be a reason to re-read that sentence and the one before it for clarity.
先写后重组，让每句从重点开头，狠心删减，并多读优质编辑文本。
最易见效的几招：从“为什么”开始（我用三层为什么，有人多有人少）；先写出来，再把每段句子顺序颠倒，让每句以你原本要引出的重点开头；杀掉你的心头好，任何你需要绕弯才能保留的表达都没你以为的那么好；多读高质量、经过编辑的写作，如《经济学人》《金融时报》《每日电讯报》，有时也读《卫报》；避免甜腻、唱歌般、充满术语和陈词滥调的社论体。
motohagiography查看英文原文
Easiest wins: - "Start with why." (I use 3 layers of why, some more, some fewer.) - Get it out, then go back and reverse the order of the sentences in each paragraph, so each one begins with the point you were getting to. - Kill your babies. Any turn of phrase you are working around to keep it in, or make it work is not as good as you think. - Read a lot of quality, edited writing. The Economist, Financial Times, Telegraph, and sometimes even the Guardian. Avoid cloying, sing-song, editorial prose that is full of jargon and cliches. Source: am a writer who codes.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选