斯蒂芬·金给技术写作人员的实用建议

图片来源

By JWilde。由 Opensource.com 修改。cc by-sa 4.0

即使你不喜欢写作，也没有打算成为一名专业的技术写作人员，你很可能在你的职业生涯中的某个时刻需要起草报告、邮件列表更新或技术文章。记住一些实用的技巧，再加上斯蒂芬·金的可靠写作建议，你可以在开始写作之前改进你的写作。而且，通过适当的计划，你可以轻松地为多个受众重新利用你的内容。

在我们深入探讨写作部分之前，让我们假设你知道你要写什么以及你为什么要写作。例如，你可能正在写作以

让你的社区了解错误修复或安全更新；
向经理提供项目状态更新；
告诉开发人员提交补丁的新流程；
或者向媒体通报最新的软件发布。

当你知道你要写什么以及你的写作目的时，你需要了解你的受众。

你的读者是谁？

在你开始写作之前，退后一步，确保你已经定义了你的受众。广义上讲，你可以将你的读者分为三类：外行、管理人员和专家。在科罗拉多州立大学的开放存取学习环境写作工作室中，Michel Muraski 解释了受众的三个类别

外行受众没有特殊的或专业的知识。他们与文章的人文趣味方面联系。他们通常需要背景信息；他们期望更多的定义和描述；他们可能想要有吸引力的图形或视觉效果。

管理人员受众可能对该主题的了解程度不高于外行受众，但他们需要知识以便他们可以就该问题做出决定。做出决定所需的任何背景信息、事实或统计数据都应突出显示。

专家可能是知识、呈现方式以及图形或视觉效果方面要求最高的受众。... 对于“专家”受众，... 风格和词汇可能是专业或技术性的，来源引文是可靠和最新的，并且文档是准确的。

如果科技记者是你应该接触的读者，而你没有经验丰富的公关团队带头，请暂停印刷。阅读《媒体的关怀与喂养》。然后再次阅读。如果科技记者是你唯一想要接触的读者，《媒体的关怀与喂养》已经涵盖了你所需的内容。否则，请继续阅读。

例如，Opensource.com 的读者可以是外行、管理人员或专家。我们可以假设我们的读者对开源软件、社区或方法论感兴趣，但我们不能假设他们都是经验丰富的开发人员。例如，如果我们有一篇提到微服务的文章，我们不应该假设所有读者都知道这意味着什么，因此我们需要提供定义或链接到资源。另一方面，我们不需要为阅读名为“你的文档何时需要屏幕截图？”的文章的任何人解释文档，因为我们可以假设只有编写文档或对文档感兴趣的读者才会阅读它。（有关编写项目文档的绝佳建议，请阅读“RTFM？如何编写值得阅读的手册”。）

斯蒂芬·金谈写作

你已经定义了你的受众，但不要急于开始写作。相反，给自己倒一杯咖啡或拿点零食，然后开始阅读。

因为我一直在思考写小说，所以我空闲时间一直在读很多小说。去年夏天，我还读了斯蒂芬·金的《写作这回事：创作生涯回忆录》。虽然他的书是关于小说写作的，但他的许多观察也适用于技术写作。要成为一名优秀的技术写作人员，你需要阅读技术内容。

1. 好的写作需要阅读

如果你想成为一名作家，你必须首先做两件事：大量阅读和大量写作。我不知道有什么方法可以绕过这两件事，也没有捷径。~ 斯蒂芬·金

当然，你可以只在不得不写的时候才写，但每次都期望这会是一场挣扎——甚至可能是折磨。是的，很多作家都不太喜欢阅读，但他们通常不是好的作家，而且他们写的东西不一定值得阅读。

如果你被分配了写作任务，请明确期望。阅读示例会有所帮助。例如，如果你的经理想要项目状态更新，阅读示例更新或包含信息的列表将帮助你满足期望。如果你被期望为公司博客贡献一篇活动报告，请阅读公司博客或类似网站上的先前报告。在为技术出版物撰写文章之前，请阅读几篇类似的文章，以了解编辑在寻找什么以及读者期望什么。

在你完成阅读并对预期结果有所了解之后，花点时间考虑如何重新使用你的内容。如果你计划为多个受众撰写关于同一主题的文章，请在写作过程中牢记这一点。例如，在为我在欧洲 LinuxCon 上做的演讲“说他们的语言：如何为技术和非技术受众写作”做研究时，我意识到先写一篇文章会使我的演讲计划更容易。如果我先计划我的演讲，我很有可能不会再回去写更长的文章（在这种情况下，是一篇文章）。在任何一种情况下，研究都是相同的，但一种方法（先写文章，然后演讲）比另一种方法（先写演讲...永远不会抽出时间写文章）更有效地利用时间。决定我可以为 Opensource.com 的读者以及 LinuxCon 会议的与会者写作，这帮助我决定先写哪篇文章。

示例：为专家受众（开发人员）写作

Greg DeKoenigsberg，Ansible（一种流行的开源自动化工具）的社区副总裁，需要让开发人员了解新的流程，因此他为开发人员邮件列表撰写了公告。在他的消息“Extras 中接受新模块的新流程”中，他不需要定义Extras是什么，因为 ansible-devel 邮件列表的受众应该已经熟悉这个术语。

Greg 的邮件列表帖子也适用于 Ansible 开发人员博客文章。

示例：为外行受众（社区）写作

Robyn Bergeron，Ansible 的社区架构师，也写了关于相同的流程变更，但面向更广泛的社区受众。在她题为“Ansible Extras 模块 + 你：你如何提供帮助”的博客文章中，Robyn 的受众范围并没有缩小到 Ansible 开发人员的邮件列表，因此她在第一句话中定义了她的受众

这使我们得出斯蒂芬·金的第二个教训。

2. 邀请读者。

你可以稍后回去修改你的介绍，但首先用一两句话抓住读者的注意力，并告诉他们期望什么。

开头的一句话应该邀请读者开始阅读故事。它应该说：听着。进来这里。你想知道这件事。~ 斯蒂芬·金

强有力的介绍也有助于你，作者，专注于你的受众和目标。

3. 讲述一个故事。

斯蒂芬·金有很多关于讲故事的建议，而这正是技术写作人员正在做的事情。

当你写一个故事时，你是在给自己讲故事。当你重写时，你的主要工作是删除所有与故事无关的东西。~ 斯蒂芬·金

任何对故事不重要的东西都可以省略。你是否正在编写关于如何开始使用开源图形程序的 HowTo？考虑链接到项目网站上的安装说明，除非文档中没有这些说明。

4. 省略无聊的部分。

当人们问我他们的文章应该有多长时，答案是尽可能长。除非你在狭小的空间（例如，一页印刷杂志）中写作，否则字数限制非常灵活。但是，如果你发现你为一篇技术文章写了超过 1,000 个字，或者为项目更新写了 500 个字，请重新阅读你的文本，看看你是否不小心包含了无聊的部分。金说要省略那些部分。

大多数时候，当我想到节奏时，我会回到埃尔莫尔·伦纳德，他非常完美地解释了这一点，他说他只是省略了无聊的部分。这表明要通过删减来加快节奏，而这正是我们大多数人最终不得不做的事情（杀死你的宠儿，杀死你的宠儿，即使这会让你以自我为中心的涂鸦者心碎，也要杀死你的宠儿。）~ 斯蒂芬·金

如果你的文章超过 1,000 字，并且没有无聊的部分，请考虑将你的文章分成更小、更易于消化的块，例如分为两部分的系列文章。

例如，Greg 发给 ansible-devel 邮件列表的帖子省略了关于开发模块的详细信息。相反，他提供了模块指南的链接。毕竟，他不是为 Ansible 模块开发人员受众写作，因此他可以省略那些无聊的部分。

在面向更广泛的 Ansible 社区受众的示例博客文章中，Robyn 提供了简要的背景介绍

关注各种 Ansible 存储库的人可能已经注意到，你友好的邻居 Ansible 社区团队...一直在挖掘相当多的问题和拉取请求积压，主要是在 Extras 和 Core 模块存储库中。... 我们确定的主要问题之一是，简单地说，流程中的瓶颈...

在陈述问题之后，她解释了解决方案

因此：一个新的流程诞生了。我鼓励你阅读详细信息，特别是如果你有兴趣帮助进行审核，或者已经为 Ansible 做出贡献，Greg 在星期五在 ansible-project 和 ansible-devel 邮件列表中概述了这些详细信息。话虽如此，以下是重要的亮点...

对于社区受众，Robyn 链接到了无聊的部分，其中包括 Greg 面向更技术受众的帖子，以及 Ansible 文档、模块指南以及如何贡献。

大纲

除了强有力的介绍之外，大纲还可以帮助你专注于你的受众和目标。以下是一些示例大纲

新闻或社区公告

介绍（邀请读者进来）
提供简要背景（陈述问题）
分享新闻（解释解决方案）
结论（包括重要日期或行动项）

技术文章、教程或白皮书

介绍（邀请读者进来）
提供简要背景（陈述问题）
分享新闻（解释解决方案）
深入技术细节（HowTo 步骤、FAQ）
结论（包括重要日期或行动项）

根据你所写的内容，你可能希望在结论之后包含其他资源，例如文档链接、媒体联系人或社区资源，例如社交媒体帐户、IRC 频道和邮件列表的链接。

《媒体的关怀与喂养》建议在新闻稿中包含一份情况说明书，但要包含的事实清单也适用于项目更新和公告。情况说明书应包括

产品是什么
首次发布时间
它在哪些平台上运行
配置要求是什么
价格是多少
媒体联系人
面向公众的 URL 和其他联系信息

产品是什么、首次发布时间、它在哪些平台上运行、配置要求和成本都最好在公告或文章的开头包含。

在你完成草稿后，休息一下，然后用全新的眼光重新审视它。在进行修改之前，从几位同事那里获得反馈是个好主意。如果你不与任何有丰富写作经验且了解你的主题的人一起工作，请联系你的网络。理想情况下，你希望获得来自会非常诚实和彻底的人的反馈，而不是会让你自我感觉良好的人。无论如何，请记住，如果你不同意所有建议的修改，你不必接受它们——你的名字与你的作品联系在一起，所以计划对最终草稿中的内容负责。