技术写作建议

在与杰出的技术作家和Smashing Magazine 主编Rachel Andrew 的最近的一次播客 之前，我收集了许多关于技术写作的思考和参考资料。多年来，许多聪明人说了很多聪明的话，我认为我会整理一些我最喜欢的建议，并加上我自己的经验，作为也做过不少技术写作和编辑的人。

技术写作的世界要大得多。我的经验和兴趣主要集中在网络技术和博客方面，所以我从这个角度切入，我引用的许多人也都来自这个领域。

选择写作主题

如果你想为 CSS-Tricks 写作 并问我应该写什么，我可能会反问你这个问题。我可能还不够了解你，无法为你选择完美的主题。更重要的是，我真正希望你写的是对你来说个人且重要的东西。基于你对特定想法或技术的最新兴奋的文章总是比指定的任务做得更好。

我的最佳建议

写下你希望你在谷歌搜索时能找到的那篇文章。

— Chris Coyier (@chriscoyier) 2017 年 10 月 30 日

也就是说，我确实维护着一个专门针对这个网站的想法列表。任何写作都可以在任务中完成，有时这会激发出创造出伟大的作品，并与网站受众目标一致的火花。

在学习的时候写作

你学习某件事的那一刻就是最好的写作时间。它还很新鲜，你可以回忆起在你理解它之前是什么样子。你也能理解从不知道到知道它需要什么。这就是你需要带领人们走的旅程。

如果你没有时间，至少尝试在你保存想法的地方捕捉到那种氛围。不要只写下“数据集”。写下一些简短的笔记，例如，“我之前没有意识到 DOM 元素有一个.dataset 属性用于获取和设置数据属性。我想知道它是否比getAttribute更好。”这样，当你再次思考这个想法时，你就可以重新加载这种想法。

你在最近几天学到了什么？我敢打赌，那里有一篇博文。 Manuel Matuzovic 在他的博客“今天我学到”（TIL）部分出色地践行了这一点。

比较技术是一个未充分利用的格式

以下是 Rachel 分享的一些建议，我认为人们对这些建议的利用还不够。

技术文章和教程有一个最佳点。为那些还没有时间学习某件事的专业人士写作，并将它与他们已经了解的东西联系起来。例如，向了解 jQuery 的人解释现代 JS 技术。

— Rachel Andrew (@rachelandrew) 2019 年 2 月 20 日

告诉我这个新框架与 Backbone 有什么关系。告诉我这个CMS 与 WordPress 有什么关系。告诉我一些技术如何与另一个技术联系起来，可以假设这个技术更广为人知。

技术变化很大，但技术的作用并没有发生太大变化。

小心那个引言

我在审阅教程时最常加的评论是要求在引言中描述教程的内容。我读了 600 个字，但仍然不知道教程是关于什么的，以及它是为谁准备的。 #写作

— Rachel Andrew (@rachelandrew) 2018 年 1 月 5 日

技术文章开头没有切入主题，这简直是流行病。技术文章的开头不是抒情或发表一些像“网页设计确实发生了很大的变化”这样的陈词滥调的时候。你不必枯燥无味，但你需要告诉我这篇文章将要讲什么，以及它是为谁准备的。

Brian Rinaldi 说:

“标题是否让文章听起来很有趣？”如果标题让读者感兴趣，他们通常会阅读引言并决定，“值得花时间阅读整篇文章吗？”我在许多技术文章中看到的常见错误是引言太多或太少。

一段写得很好的文字就可以为一篇技术博客文章奠定基础。

标题也要小心

我记得几年前与内容策略师 Erin Kissane 的一次对话，她强烈建议我为所有内容选择平淡的标题。不只是博客文章的标题，而是所有内容，包括部分名称、标签，甚至文章中的小标题。

平淡的好处在于：它有效。平淡也不是合适的词，应该是清晰。世界上充满了点击诱饵，也许在某些类型的内容中它很有效，但技术博客不是其中之一。

一个清晰的博客文章标题：GraphQL、Phoenix 和 React 入门指南，作者：Margaret Williford

同一个标题的糟糕版本：30 分钟内使用现代技术构建一个 Web 应用程序！

什么是 Web 应用程序？什么技术？什么是现代技术？为什么要设置奇怪的时间限制？

SEO很重要，Margaret 的文章使用这个清晰的标题，在短期和长期内都会做得更好。

结尾部分

Ben Halpern 说，在引言之后，第二重要的事情是

[…] 最后一段。

人们在到达时不会从上到下阅读，因此很有可能这是人们阅读的第二段。就我个人而言，我认为开头比结尾重要得多，但结尾也有一定的艺术性。

许多人只是<h2>结论</h2> 并写几句话来概括刚才的内容。老实说，我不讨厌这样做。它符合这种经过时间考验的模式

1. 告诉他们你要说什么
2. 告诉他们
3. 告诉他们你说了什么

这有助于你的信息被吸收，并使事情形成一个完整的循环。从这个意义上说，技术博客与营销并没有太大区别。你试图让人们理解某些事情，并且你会使用任何必要的技巧来完成这项工作。重复是一个经典的技巧。

使其可扫描

Brian Rinaldi 说:

[…] 一大段文字可以通过使用分割文字的视觉元素来轻松地变得不那么令人生畏，并且显得更具视觉吸引力。最简单的方法就是简单地在文章中添加部分小标题。

我同意：小标题可能是最简单也是最有效的可扫描性技巧。

其他方法

• 列表：就像我现在正在做的事情一样！我本来不需要使用列表。段落可能也适用，但列表在这里具有语境意义，并且可能正在诱使你们中的一些人阅读它。或者至少浏览一下，并在过程中了解一些关键要点。
• 图片：请确保它们相关且具有语境。跳过有趣的 GIF。截图在技术环境中通常很有效，因为它们为可能难以解释的概念提供了视觉说明。我也喜欢Unsplash 的主题图像，但你可以做得比随机的树木、喝咖啡的女人或随机的服务器机架照片更好。
• 插图：插图的抽象性质是你的朋友。它会诱使人们快速思考你正在描述的内容。它们通常需要一些工作才能完成，但对您和读者来说回报可能是巨大的。
• 视频： 你不能简单地将一个 42 分钟的视频放在一篇博文的中间，但如果你能清楚地表明你正在展示一些视觉效果，并且视频时长不到一分钟，它会是一个强有力的选择。你也可以使用 `<video autoplay muted loop controls>` 来让它像 GIF 一样。
• 代码块： 技术博客文章通常是关于代码的。不要回避代码，拥抱它。我喜欢 Dan Abramov 在博文中加入代码块 的方式，它不仅用于演示语法和设置，还用于阐述观点。我还要推荐 嵌入式 Pens，因为它们是完全交互式的演示，除了作为代码块之外。
• 表格： 不要忘记表格数据！以表格的形式呈现信息（尤其是数据或定义）比其他任何方式都更容易理解。
• 可折叠部分： `<details>` / `<summary>` 元素 可以轻松地 创建可折叠内容。如果你有一大段内容，虽然不错但并不需要每个人都阅读，那就将其折叠起来！我们关于 设备媒体查询的参考指南 就是一个很好的例子。

无论你在这里选择什么，你都应该选择有助于增强你所表达观点的东西，即使在某种程度上它感觉像是欺骗。这是为了提高可读性的欺骗，这是一件好事。

我最喜欢的技巧？一点设计。使用间距、颜色和对齐等设计原则来提高文章的可读性。我们甚至会对一些文章进行艺术指导，其中 设计可以增强 文章的核心观点。

这里重点不是完全消除长篇大论。有时这正是需要的，因为你要求读者深入阅读一段文章，否则他们就无法理解内容中需要的东西。然而，大多数情况下，文章可以通过一些合理的空白使用而受益匪浅。

使用主动语态

我发现这个有点难以理解，但 Katy Decorah 有关于 技术写作的精彩演讲，详细解释了这一点。它有点像使用现在时态，直接陈述观点而不是被动地陈述。

被动：“文件下载后……”
主动：“下载文件后……”

被动：“请求由服务器处理。”
主动：“服务器处理请求。”

这里还有另一个清晰的解释，并带有 Neal Whitman 的示例，由 Mignon Fogarty（语法女孩）朗读。

有一些词需要避免

“Just” 就是一个重要的词。 Brad Frost

“Just” 让我感觉像个傻瓜。“Just” 假设我来自特定背景，在大学学习过特定课程，精通特定技术，并且阅读过所有正确的书籍、文章和资源。“Just” 是一个危险的词。

还有很多其他的词需要避免，我之前 写过关于这些词的文章。阅读最后链接中的评论。简而言之：在技术写作中，有很多词弊大于利，不仅因为它们会让人感觉居高临下，而且因为它们 _通常_ 不会帮助它们所在的句子。尝试从任何句子中删除 “just”。句子仍然有意义。

注意你的语气

语气指的是你在考虑语境的情况下如何表达。例如，你不会用快乐的语气向某人传递坏消息。你的表达方式应该与情况相符。

这是我们这个网站的语气目标

友好。权威。热情。我们都在一起。灵活（对想法不教条）。感谢。

MailChimp 有关于他们的 非常全面的指南。

值得指出的是，语气和语调是两个不同的概念。我喜欢把语调看作是不变的（它是你的个性，是你的身份的一部分），而语气则会根据语境而改变。换句话说，你可以用专业的语调进行友好的沟通。

我不认为存在一种 _唯一正确_ 的语气，它完美地适用于技术写作，但由于任何技术写作的最终目标都是帮助人们理解复杂的东西，你可以使用语气来帮助他们。在一组复杂的步骤中间插入一个笑话会让人感到困惑。一堆！激动！可能会让人感觉不合适或不真诚，但平淡无奇和毫无生气更糟。我想说，如果你用自己的名字写作，那就让我们感受到你的一点个性，只要不影响清晰度。如果你用品牌名写作，就匹配他们已经确立的风格，无论它是否已经编纂成文。

注意长度

在技术写作中，普遍的倾向是写 _太多_ 而不是太少。 Wade Christensen

无论是因为学校作业的字数最低限度，还是仅仅是因为缺乏批判性思维，我们大多数人写得太多。除了以冷酷的删减心态来对待每一篇草稿外，还有几种方法可以从第一篇草稿开始就写短一些。

字数限制可以有所帮助，即使是自我强加的。

我最近听到一个新晋编辑说，他很难让他的作者提交字数少的文章，所以他建议他们将字数限制在 1000-1500 字之间作为指导，这似乎很有效。作为比较，这篇文章大约是上限的两倍。

真正的解决方案，如果有资源，就是冷酷无情的编辑。

我个人认为，写得过长并不是唯一的问题。我也遇到过很多作者写得过短，没有深入挖掘主题的情况。我不喜欢关注长度；我喜欢关注内容本身的清晰度和实用性。

旁注：将一篇博文分成多个部分（作为系列文章中的单独博文）并不是解决文章过长的办法。实际上，它可能会加剧问题。只有在不同部分在主题上有所不同，并且可以独立存在的情况下，才能这样做。

不要阻止自己写作

有一种无形的力量，它是由恐惧构建的，它阻止了很多人参与技术博客。“嗯，每个人都知道这个，”你可能会想。（他们不知道）。“如果我错了，有人会指责我怎么办？”（如果你做的事情对你有用，你就不会错。）

即使你克服了这些恐惧，开始将文字写到屏幕上，也可能还会遇到障碍。这里有 Max Böck 的观点

我在写作的时候会发生一件事。我从一个新想法开始，兴奋地把它写成文字。但随着时间的推移，我失去了信心。

Max 的技巧是不要等太久，忽略那些让你退缩的感觉

只要我觉得我想要表达的所有重要观点都包含在内，我就会立即发布一些东西。我会试着无视那个尖叫着 “还没准备好” 的声音，足够长的时间把它发布到网上。

Jeremy Keith 甚至说 我们甚至不应该保存草稿

我认为保存草稿可能会适得其反。问题是，一旦某个东西成为草稿而不是博文，它很可能就会一直是草稿，永远不会成为博文。而某个东西在草稿状态中保存的时间越长，它就越不可能见到天日。

你的写作帮助到别人的可能性非常高！ Matthias Ott:

即使是最小的文章也能帮助到外面的人。

你认为自己经验不足吗？你可能并不，但即使你真的经验不足，一个经验不足的人的观点仍然有用。 Ali Spittel

如果你有一篇博文，其中大部分信息都是正确的，或者至少是你对该主题的理解，那么你就足够有经验了。有很多来自新手视角的优秀文章，它们非常重要！

恐惧在写作中是真实存在的，与之抗争可能会让人崩溃。虽然这本书主要针对创意写作，但 《艺术的战争》 作者 Stephen Pressfield 的这本好书可以帮助你突破恐惧。

没有一种完美的风格

我们每个人都有自己独特的视角和写作风格。一种写作风格可能更容易被某些人接受，因此可以帮助并惠及大量（甚至少量）的人，而这些方式可能超乎你的预期。

…如Sara Soueidan所说。她继续说道

只需写作。

即使只有一个人从你的文章中学习到了一些东西，你也会感到很棒，并且你为这个我们都在不断学习的惊人社区做出了贡献——即使只是一点点。

技术博客文章不必没有创造力。你可以创建一个很棒的技术博客文章，其中包含两个开发人员之间学习彼此的注释聊天室对话。或者一篇博客文章，是一系列互相补充的视频。

越入门，标准越高

网络上充斥着初学者级别的表面文章。有大量的速成课程、101 和介绍性内容。如果你想从人群中脱颖而出，并变得有用，你必须打败对手。

对于面向初学者的文章，并没有必要改变语气。你不需要像说话缓慢或贬低别人一样。你只需要清晰，清晰对于任何技能水平的读者来说都是宝贵的，更不用说他们也会欣赏它。一个非常高级的程序员可以而且会欣赏技术博客文章中的清晰度，即使它是一些他们已经理解的内容。

但总体而言，标准并不高

你不需要十年的经验就能写一篇博客文章。我认为，它更像是需要一天的经验、写作的愿望以及有话要说。我认为你会惊讶于写出一篇引人注目且可读的博客文章需要做的很少。付出一些努力，阐明观点，专注于可读性，你就会做得很好。

我希望这篇文章中的建议对你有帮助！

抽象很有用，但现实世界的例子有时更好

Christine 写道:

描述一个高级概念是一回事，而解释或说明这个概念如何在现实世界中应用则是另一回事。在技术写作中，你通常会涵盖复杂或难以理解的主题，因此使用恰当的例子来展示你的主题为什么重要，或者它如何与现实世界相关，就更加重要了。

我发现，我比反对过于关注现实世界用例的代码更倾向于反对过于抽象的代码。我更喜欢看到 ["Charles Adok", "Samantha Frederick"] 而不是 ["foo", "bar"] 或 [a, b]，但更重要的是，然后如何处理这些数据，使其感觉像一个相关的编程场景。

但要避免以清晰度为代价的现实世界例子。如果抽象有助于在不陷入细节的情况下阐明一个复杂的观点，那就这样吧。

博客打开了大门

我遇到的所有积极写博客的人，都表示博客对他们的职业生涯产生了积极的影响。除了公开展示你思考和表达想法的能力之外，它还能帮助你更好地理解事物。教就是学。

我认为我自己的博客是我所取得的任何成功的最大贡献者。这是 Khoi Vinh，一位比我成功十倍的设计师

很难夸大我的博客有多重要，但如果我尝试用一个词来概括，那就是：“放大器”。

你对所做的事情越来越好。

这是不可避免的：练习让你变得更好。关于练习的期望有时非常明确，并且植根于文化。为了弹钢琴弹得更好，你需要上钢琴课并练习。我们都知道这一点。但人们也会说：“哦，我是一个糟糕的厨师”，仿佛烹饪作为一项技能与弹钢琴在本质上有什么不同，并且不需要同样的学习和练习。

你通过更多地写作来提高写作水平。也就是说，**有目标地写作**。写作，然后公开发布你的作品，以便人们阅读。

你可以去学校学习写作。你可以找一个写作教练。我的想法是，没有什么比经常写作更有效果了。无论你投入时间做什么，你最终都会精通。一万小时 框架对你来说有效吗？那就用它吧。事实上，我发现即使那些整天坐在电视机前看电视的人，最终也会非常擅长看电视。

你的声音 < 带有背景的故事 < 包含他人的故事 < 研究和数据以及包含他人的故事

一篇你只是说一些东西的文章是可以的。你可以说一些东西。

但你可以做得更好。

一篇你讲述一个关于某件事如何对你有用的真实故事的文章会更好。背景！现在我们可以更好地理解你所说的话背后的来龙去脉。此外，每个人都喜欢故事。

一篇你将此与引用**他人**的写作和故事结合起来的文章会更好。现在你正在描绘一幅更大的图景，并帮助验证你所说的话。背景*和*风味！

一篇你将所有这些与研究和数据结合起来的文章是最好的。现在你正在表达个人观点，承认自己之外的世界，加入背景，并避免过于轶事。砰！现在你正在写作了！

你在推销吗？

阅读网站关于客座写作的内容。这是我们的。

并不是想吓唬你，但90%的投稿都是垃圾。也许75%是纯粹的垃圾邮件，另外15%是那些显然没有阅读我们关于客座投稿的任何内容，并且完全偏离主题的人。我通常可以**从电子邮件本身的写作质量**判断出他们是否会成为一位优秀的客座博主。

我说这些话，然后又不得不提醒你标准并不高.

有哪些有用的工具？

可能会有，但我不想把你链接到我无法保证的工具。我使用的只是Dropbox Paper 进行协作写作，因为共享模型很简单，允许共同编辑和评论。另外还有Grammarly，因为它可以捕捉到你在写的时候犯的大量错误。

📝🎉