技术写作与文档2018blog.stoplight.io编辑精选
当你不是技术写作者时，如何写文档
Writing Documentation When You Aren't a Technical Writer
导读
这是一篇写给"不是专业技术写作者"的人看的文档写作指南（第一部分），讲如何组织信息、安排代码示例等具体技巧。值得写作者读的地方在于：评论里几位资深技术写作者把话题拉回到更根本的原则——先弄清读者是谁、带着什么知识和情绪来读，再谈其他技巧；另外关于代码示例的两条经验（别示范反模式、从真实代码中抽取片段）对所有写教程的人都适用。
可以直接用的写作要点
- 01
动笔前先明确读者：他们已经知道什么、你假设他们知道什么、他们此刻的情绪（比如查错误码的人往往很慌），再决定开篇该放什么"最重要的信息"。
- 02
示例里不要出现你自己认为是反模式的写法；如果为了简洁必须展示，就在代码旁标注并说明正确用法，否则读者会照着学错。
- 03
为每个选项或功能说明它适合什么场景、解决什么问题，别让读者猜你当初为什么要加它。
- 04
把代码片段放在能真正编译、跑测试的仓库里，写作时从那里引用，而不是直接手写在文档里——手写的片段迟早会过时。
HN 评论精选
一切写作技巧都服从于一条总原则：了解读者并为这类读者而写。
我是技术写作者，负责 Chrome DevTools 和 Lighthouse 的文档。这篇文章的建议大体没问题，但讽刺的是它自己没遵守自己的建议（"前两段必须写出最重要的信息"）。写高质量文档最关键的技能是了解你的读者，然后为这类读者而写：他们带着什么已有知识来（因此你不必讲）？你假设他们知道什么？如果他们其实不知道呢？——那他们多半会觉得你的文档令人困惑、令人恼火。他们读文档时的情绪状态如何？比如你在写某个错误码的说明，读者很可能正处于慌乱中，别浪费他们的时间。对特定读者来说，究竟什么才算"最关键的信息"？"了解你的读者"这种事越想越觉得自己懂得少，是一辈子的功课；但你越专注于此，你所有的沟通都会变好。我可以讲上几年各种写作技巧，但如果没有这条总原则，一切都是白费。
kaycebasques查看英文原文
I'm a technical writer. I write the docs for Chrome DevTools and Lighthouse. The tips in this article are mostly fine. Nothing controversial there. It has some good advice, but ironically, the article itself doesn't follow its own advice. > The first two paragraphs must state the most important information. The most crucial skill for creating quality documentation is to know your audience and then write for that particular audience. What knowledge are they bringing into the doc (and therefore you don't need to cover)? What knowledge are you assuming that they know? What if they don't have that knowledge? Hint: They'll probably find your doc confusing and frustrating. What is their likely emotional state going into a doc? E.g. if you're documenting an error code there's a higher chance that they're panicked, so don't waste their time! Given a particular audience, what exactly is "the most critical information"? "Know thy audience" is one of those concepts where, the more you think about it, the less you realize you know. It's a lifelong journey. But the more you focus on this concept, the better all of your communication will get. I could go on for years about all sorts of interesting tips for improving your writing, but it's all a waste of time if you don't have an overarching guiding principle. And that principle is to know and write for your audience.
示例别示范反模式、要说明功能的使用场景、废弃内容必须给出替代方案。
关于文档的几点想法：1）示例里不要做你自己认为是反模式的事。几年前 Angular 1.x 的文档就示范了作者自己都认为是反模式的写法——你教给用户错的用法，又凭什么惊讶他们在用错？如果为了简短必须给反例，至少要在代码旁注明并解释正确用法。2）说明某些功能或选项可以用在什么场景。我常遇到一些库提供了奇怪的选项或方法，我始终不明白它们的用途；你既然加了这个选项，总该想到过某种用例吧？当你不熟悉某个领域、想积累它的用例知识以备日后处理相关问题时，这类说明很有用。3）如果某个东西已废弃或不推荐使用，一定要把用户指向正确的替代方案。我在 MDN 上见过提示你使用某个 API 的警告框，点进去却发现那个 API 已废弃、文档说你不该用它——自相矛盾的信息非常让人抓狂。
TheAceOfHearts查看英文原文
Some thoughts on documentation: 1. Don't do things in your examples which you consider anti-patterns. A few years back I remember some Angular 1.x docs which showcased certain examples which the authors considered anti-patterns. Why are you surprised that users are doing things the wrong way if you're the one that taught them? If you must provide an anti-pattern examples for the sake of brevity at least note it near the code sample and explain what the correct usage should be. 2. Give examples of what certain features or options could be used for. I sometimes encounter libraries which provide weird options or methods for which I never understand their purpose. If you added the option it means you must've thought of some use-case for it, right? It's pretty useful when you're not familiarized with a domain and you want to build up the knowledge of its use-cases in case you have to deal with related problems later on. 3. If something is deprecated or its usage is discouraged be sure to point users to the proper solution. I've encountered warning blocks on MDN which suggest using a certain API, but when you click through it turns out that it's deprecated and they tell you that you shouldn't use it. Contradictory information is incredibly frustrating.
代码片段要从可编译、有 CI 的真实代码仓库抽取，而不是手写在文档里。
我在 Google 做开发者关系四年多，文章里关于代码片段的观点非常好，我再补一条：想办法让你的代码片段来自真实代码。也就是把片段写在能用正常编程工具的地方，确保它们都能编译，把这个片段仓库发布到 GitHub 之类的地方；在文档系统里让文档在生成页面时从仓库拉取片段。这个仓库要有基本的 CI 来保证代码和依赖是有效的。如果你直接在 Markdown 或 HTML 里手写片段，它们最终一定会出错；即使一开始是对的，等 API 升到 v2 时更新起来也极其痛苦。我见过的每个自以为可以例外的团队都错了。
habosa查看英文原文
Ive been doing developer relations at Google for 4+ yrs now and the points about code snippets in this article are great. Let me add another one though. Find a way to pull your code snippets from real code. What I mean is, write the code snippets somewhere that you can use a your normal coding tools and make sure they all compile. Publish this repository of snippets on GitHub or similar. In your doc system, have the docs pull the code snippets from the repository at page generation time. This repository should have basic CI to make sure the code and dependencies are valid. If you write snippets directly in markdown or html, they will eventually be wrong. Even if they start correct, it will be a real pain to update them for v2 of your API. Every team I've ever seen that thought they were the exception to this rule was wrong.
用风格指南加自动化检查来保证文档的一致性，示例名称也要有统一规范。
我们的数据库文档采用了一套正式规范（基于 Google 开发者风格指南），并尽可能用 linter 把检查自动化：拼写、Markdown 格式、失效链接、语法和文风。比如我们明确禁止出现真实主机名、域名、IP、人名、电话号码，除非它在我们的示例清单里（该清单主要依据 RFC）。
rodionos查看英文原文
We adopted a set of formal guidelines [0] for our database docs, based on Google Developer Guide [1], and automated the checks as much as possible with linters [2]. The checks cover spelling, markdown formatting, broken links, and grammar/style. For instance, we specifically reject hostnames, domain names, IP addresses, person names, phone numbers unless it's on our Example List[3], which itself is largely based on RFCs. [0]: https://axibase.com/use-cases/tutorials/workshop/technical-writing.html#grammar [1]: https://developers.google.com/style/ [2]: https://github.com/axibase/docs-util [3]: https://axibase.com/use-cases/tutorials/workshop/technical-writing.html#example-names
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选