技术写作与文档2022news.ycombinator.com编辑精选
Ask HN：如何提升你的技术写作水平？
Ask HN: How to level up your technical writing?
导读
这是一位架构背景的工程师在 HN 上求助如何提升技术写作能力的帖子，高赞回复从“读者意识”“先搭结构再写句子”“日常练笔与叙事化表达”到具体课程与书目，给出了一套可操作的路径。对写作者来说，这些建议不只适用于技术文档，也能直接迁移到说明文、产品文档和任何“把复杂讲清楚”的写作中。
可以直接用的写作要点
- 01
动笔前先想清楚读者是谁、他们遇到什么问题，写作目标是帮他们解决问题，而不是把信息记录下来。
- 02
先把内容拆成标题、小标题（必要时再加一层），检查整体流程是否连贯、有没有缺失或该独立成篇的部分。
- 03
用“标题结构 → 要点列表 → 图表占位 → 扩写成完整句子”的顺序推进，能显著降低写作阻力。
- 04
别怕在干巴巴的技术文本里加入个性和具体例子，适度叙事能提高读者的阅读意愿。
HN 评论精选
写作前先锚定读者及其真实处境，成稿后找人编辑。
技术写作者的第一条铁律是了解你的读者：不仅要知道他们的技术问题，还要花时间共情他们为什么会有这些问题。技术写作不是“记录文档”，而是找到最好的解释方式让人解决问题。另外，请找人（真人，不是软件）帮你编辑。
marcpaq查看英文原文
Tech writer here. The absolute, invariable first rule in tech writing is to know your audience. Understand not just their technical problems but take the time to empathize with why they have these problems in the first place. Tech writing isn't about documenting, it's about finding the best way to explain something to people so they can solve their problems. Oh, and use an editor (the human kind, not the digital kind.)
先搭骨架、再填要点、最后写成句子，并适度保留个性与例子。
写技术书时出版商给我的建议是：先把要写的内容拆成标题和小标题，甚至小标题的子级，再回看结构是否连贯、有没有缺章节或该拆出去的部分。我的流程是先用要点表达想法，插入图表占位和图注，最后把要点改写成完整句子、补充例子和过渡文字。关于“简短”，我大体同意，但视媒介而定，注入一点个性也无妨——技术文本容易枯燥，会劝退读者；尽量用具体例子或引用其他支撑材料。
Gaessaki查看英文原文
Lots of great advice here. One piece of advice I got from my publisher when authoring a technical book was to first break down what I was going write into headings and subheadings, and if possible, into sub-subheadings. Then review that to see if your flow is coherent and whether there are sections that are missing, or could be extracted into another text. Personally, my process after this is to express my thoughts in bullet points, followed by inserting any placeholders and captions for any graphics (e.g. charts or diagrams), and then finally I start rewriting my bullet points into proper sentences, expanding my examples, and adding any interstitial text necessary to make things flow. Also, I see some comments on keeping things short and to the point. In general, I agree with this, but depending on the medium, sometimes it doesn’t hurt to inject a bit of personality into your writing. Technical writing can be dry at times, and this can deter engagement. Try to use concrete examples whenever possible or refer to other supporting texts.
系统学习可以借助成熟课程和写作改错类书籍。
推荐两样东西：Google 的技术写作课程，以及《Bugs in Writing》这本书——我已经向人推荐了二十年。
gnat查看英文原文
Two things I recommend: the Google tech writing courses: https://developers.google.com/tech-writing And "Bugs in Writing", which I've been pressing into people's hands for twenty years now. https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/dp/020137921X
先动笔练习，并用“执行摘要＋背景＋正文”的叙事结构组织文档。
我从高中进工学院时很羡慕文科朋友总有写论文的机会，后来意识到书面/技术沟通是巨大的差异化优势。我每天写日记，但针对这个问题我想说：先开始写。了解读者是关键：我通常在设计文档或需求文档开头放一段执行摘要，说明大家为什么要在意，然后交代背景和历史给上下文。归根结底这是一篇叙事，遵循类似的弧线，只是语言更直接、事实更具体。
mishftw查看英文原文
When I left high school for college (to pursue engineering) I was quite envious of my friends in the liberal arts - they were assigned papers all the time and I had no outlet for writing (something I enjoyed quite a bit). I have realized that written/technical communication is a great differentiator. I journal every day but specifically to your question I would say just start writing. Knowing your audience is key. I usually include an executive summary section at the top of any design document or product requirements document for a high level view of why people should care. Then I dive into a background or history to give context. At the end of the day it's a narrative and follows similar arcs - just with more direct prose and specific facts. I'll also drop this resource here from the Pragmatic Engineer newsletter. [0] [0]: https://newsletter.pragmaticengineer.com/p/software-engineering-rfc-and-design
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选