斯蒂芬·金给技术作家的实用建议

图片来源：

作者：JWilde。由 Opensource.com 修改。cc by-sa 4.0

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

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

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

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

你的读者是谁？

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

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

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

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

如果技术记者是你应该接触的读者，并且你没有经验丰富的公关团队带头，请暂停一下。阅读《媒体的关怀与喂养》。然后再读一遍。如果技术记者是你想接触的唯一读者，《媒体的关怀与喂养》可以满足你的需求。否则，请继续阅读。

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

斯蒂芬·金谈写作

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

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

1. 好的写作需要阅读

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

当然，你可以只在必须写作时才写作，但要预料到每次写作都会很挣扎——甚至很痛苦。是的，很多作家都不喜欢阅读，但他们通常不是优秀的作家，而且他们写的东西不一定值得阅读。

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

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

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

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

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

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

Ansible 的社区架构师 Robyn Bergeron 也写了关于同一流程变更的文章，但针对的是更广泛的社区受众。在她的博客文章“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 和其他联系信息

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

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