为软件工程师写作：先阅读我
开发者应该与同行分享更多知识。遵循这些建议来克服焦虑，开始写博客（或写得更好）。
译自 Writing for Software Engineers: Read Me First，作者 Charles Humble。非常棒的写作教材，之前另一篇是陈皓老师翻译的《Google 技术写作》，也在这里缅怀一下陈皓老师。
我们许多工程师都患有常见的疾病：害怕写作。这通常始于学校，在那里我们被告知我们没有“语言天赋”。这是无稽之谈。写作是一门手艺，它的原则是可以学习的。
您可能希望这样做的原因有很多。
随着我们更多的人转向远程和混合工作，以书面形式清晰沟通的能力变得比以往任何时候都更加重要。写作可以是建立个人品牌的一种绝妙方式，在这个过程中它迫使你学习和发展。
提高你的写作技巧还可以帮助你在你的职业生涯中取得进步。如果你渴望在管理或开发者关系中工作，想让自己成为一名会议演讲者，甚至梦想有一天为技术出版商撰写一本书，写作（以及前面提到的品牌建设）是实现这些抱负的核心。
此外，它给了你一个与其他知识渊博的人交谈的理由，它具有刺激性、趣味性和难度。我认为，作为工程师，我们被困难的问题所吸引。
写作和编程之间还有一些惊人的相似之处。有些是显而易见的。与编程一样，通过练习可以提高写作水平。与编程一样，你经常通过模仿学习新的写作技巧。与编程一样，写作有可以派上用场的模式，但这些模式也很诱人、迷惑人，并且容易过度使用。
你的潜意识也比你想象的做了更多的写作（或编程）。你可能花一整天时间在文章中与一个问题作斗争——或者与一段代码作斗争，只是在休息后立即想通。
我坚信工程师需要提高分享我们知识的能力，而撰写文章是实现这一目标的关键途径。作为一名曾担任工程师和 CTO 的人，现在主要以作家和顾问为生，我将分享我的方法，希望它能鼓励你们中的一些人分享更多你们的知识。
考虑到这一点，我将首先分解我的写作过程。当然，每个人的创作实践都略有不同。但思考某人如何处理工作可以是一个有用的起点。
开始写作过程
我喜欢从思考我为谁写作开始。我发现在你开始之前，心中有一个明确的人选会有所帮助。这样做的好处之一是让你可以回答诸如“他们知道什么？”和“我需要解释多少？”这样的问题。
例如，你可能会想，“我写这篇文章是为了一个担任其第一个领导角色的高级开发人员。他们可能已经专业编码了大约七八年，但还没有领导过团队。”
或者，“这是为初级开发人员准备的——可能是第一或第二份工作——他们在他们的第一个项目中使用AWS Lambda。他们了解Go，因为他们在大学学习过，但他们不太了解如何构建 Lambda 项目。”
当然，“这是一篇针对两到三年前的我这样的人的文章，在我了解这些东西之前”也是一个好的（也是常见的）起点。
了解你为谁写作的一个原因是它可以帮助你识别出对你的部分或全部目标受众来说不熟悉的术语。如果一个术语不熟悉，你可以：
- 链接到一个好的解释（不要重复发明轮子）。
- 如果你找不到好的链接，可以提供一个简短的定义。
如果你有很多这样的术语，提供一个术语表是一个不错的选择。
一旦我决定了为谁写作，我就会决定我为该读者扮演什么角色。我是记者吗？教育者？只是一个普通的程序员？
然后我问，“我想涵盖多少内容，我想说的一件事是什么？”这一点很重要，因为所有作家都渴望完整性和准确性。我在这里的最佳建议是从小处着眼。决定你要涵盖主题的哪个小角落，并尽可能地做好。
我问自己的下一个问题是，“写成什么内容？”
我建议一开始就设定一个字数预算。例如，500 字适合用来发布一个新工具或产品，并简要介绍它的功能——基本上，这是一篇新闻报道。对于博客文章或类似文章，1000 至 2000 字为标准字数。教程（尤其是包含大量代码示例的教程）和书面访谈或人物专访可能会稍长一些，但始终要力求简洁。
如果一篇文章最终真的太长了，请考虑是否可以将其分成两部分或更多部分。但请注意，互联网上充斥着第一部分文章，却没有第二部分，所以请尝试在发布第一部分之前写完整篇文章。
其他前期决策
事前需要做一些其他决定。一是，你要以第三人称（作为观察者）还是第一人称（作为参与者）来写？一个相关的问题是你打算使用什么时态；大多数人主要用过去时写（“我前几天尝试用 Go 写作”），但你也可以尝试用现在时写（“在黑掉一些 Go 代码的同时，我正坐在飞往旧金山的飞机上”）。
无论你决定怎么做，都坚持下去。对于读者来说，在一个段落中来回切换视角和动词时态会让人感到不适。
另一个需要提前考虑的事情是你是否需要进行任何采访。对于你自己的博客，也通常适用于公司博客，你将表达一种观点。对于外部出版物，你更有可能需要多个来源并进行采访以获取报价。这里维护人脉非常有帮助，这样你就有便于联系的人脉。
在进行任何采访之前，我通常会写一个粗略的初稿，以便找出我想填补的空白。然后我会在联系之前预先计划问题。采访结合了预先计划的问题与即兴对话，但我发现计划对于获得良好的结果至关重要。
通过电子邮件、通过 Zoom 等会议平台在线或亲自进行采访。我以前倾向于电子邮件，但随着经验的增加，我开始更喜欢通过视频通话进行采访。与其手忙脚乱地用手记笔记，最好是在征得受访者许可的情况下录制视频或电话采访，并且一些人工智能 (AI) 驱动的应用程序可以提供语音转文本转录，从而更容易准确地引用来源。
撰写草稿
如果我作为一名编辑的经验有一点依据，作家似乎会对他们最初的草稿产生奇怪的依赖感。尽量避免。相反，将你的最初草稿视为通过对你行之有效的方法来探索你的问题域，而不要像首先编写测试用例或绘制 UML 图表那样。
当你开始写作时，你经常会发现素材会以你所料之外的方向流动，并且你做出的部分前期决策可能不是正确的。这无关紧要。让素材带你到它想要去的地方，然后稍后再审阅并优化它。
当开始一项工作时，我不会过多考虑它的发展方向。我发现空白页面令人望而生畏，所以我倾向于不考虑太多就在屏幕或纸张上写下文字，然后在获得草稿后对它们进行整理。
我还发现，如果用手写而不是在屏幕上打字，我的写作风格会有很大不同。我通常使用计算机工作，但我觉得尝试两种方法并找出最适合你的方法是值得的。我是个诵读困难者，所以我尝试通过听写进行写作，但结果对我来说永远都不太令人满意，但你可能会取得不同的效果。
你必须善于丢弃素材。我经常发现我最终会删除最初草稿的前两或三段，因为它们不够好；The New Stack的主编Heather Joslyn将这些一次性段落称为“清嗓”，我很喜欢。你会惊讶于我编辑过多少文章，我会在其中将最初的几段作为开头给删掉。
我在 Pages 中起草，部分原因是我使用 Mac，部分原因是我觉得它不引人注目，但主要是因为我知道我会在其他地方提交这篇文章——通常以 Markdown、HTML 或 Google 文档的形式，具体取决于发布者。这类似于为应用程序制作一个一次性原型，这在现实中我们并不经常做，但可能会有用。
在关于讲故事艺术的大师班上，作者Neil Gaiman说，“做你的第二稿是让你看起来好像你一直在做自己知道的事情的过程。
”我通常会转到 Google 文档进行第二稿，因为它支持跟踪更改和版本控制，这有助于编辑，允许评论并且非常适合协作。开源 Docs to Markdown 插件虽然并非完全没有漏洞，但通常可以很好地将文本从 Google 文档中提取到 HTML 和 Markdown 中，具体取决于你的内容管理系统需要什么。
第二稿是我开始考虑作品的结构和它是否合乎逻辑的地方。这就是了解你的读者真正开始产生红利的地方，因为你可以问自己诸如“这个人首先想了解什么？”这样的问题。
如果我在没有编辑的情况下工作，那么一旦我对稿件感到满意，我就会找其他人——通常是我饱受折磨的妻子——来阅读我的第二稿。如果我与编辑合作，我通常会将第二稿发送给他们。
在发布或提交之前，我通常会将草稿发送给任何我采访过的人，以确保他们对自己的引述感到满意。它有助于培育未来采访中的联系人，并有助于防止诉讼。我也经常通过这种方式收到有用的反馈；我只有一次遇到受访者想要进行大量更改的重大问题。
理解写作模式和结构
如果你在易受影响的年龄阶段读过“四人帮”设计模式这本书，然后发现自己在代码中到处使用工厂方法和装饰器，你就一定会熟悉模式的一个问题：它们很有用，但过度使用它们很诱人。
公式化写作名声不佳，但记者与所有作家一样，有时依赖久经考验的模式，我认为学习一些模式无害。
倒金字塔
倒金字塔结构是最广泛使用的一种写作模式。它通常用在新闻中，但在其他各种类型的文本，包括博客、社论专栏和营销资料中也有广泛的应用。
可以把它看成是一个重要性的递降层次结构。从最有价值的事实开始，然后用段落对论点进行支持，越往后内容越深入。
这种结构的关键在于开篇段落，它应当条理清晰、简洁明了地概括出最重要的信息，以激起读者的兴趣。
在这个结构中，最重要的句子是第一句。如果你的读者不想读第二句话，那你的文章就已经凉了。诀窍在于写出能像钩子一样吸引读者的句子，不断鼓励他们读到最后。
下面是 The New Stack 的新闻编辑达里尔·K·塔夫特写的一个新闻开头示例：
“尽管最近喧嚣不断，有人说微软为了 Rust 语言而不再怎么使用 C# 编程语言了，但微软表示它仍然致力于 C#”。
从这句话中你可以学到很多。你可以得知很多人都在说微软为了 Rust 语言而放弃 C#，并且可以推断出微软肯定在自己的项目中使用了更多的 Rust。你还可以得知微软对这种说法足够关注，以至于发布了公开声明来否认这些谣言。
沙漏式
叙事性写作通常用于报纸和杂志的特写。叙事有两部分：一个故事和一个故事讲述者。故事讲述者更像一个剧作家或小说家 - 描绘人们在生动的环境中彼此互动。它不在技术写作中经常使用，但它可以是撰写案例研究的有效方法，例如。
写这种文字的挑战在于你可能会忘记你正在尝试讲述的新闻故事。沙漏模式通常归功于记者和写作教练Roy Peter Clark，旨在结合叙事和倒金字塔风格的优点。
沙漏故事分为三部分：
- 一个倒金字塔，总结最值得关注的信息在顶部。
- 一个故事叙述，允许作者深入详细地展开故事。
- 转折或枢纽，标志着两种格式之间的过渡。
聚焦式
聚焦风格多年来一直被华尔街日报使用，经常用于头版专题。
同沙漏一样，焦点风格的广泛目标是尝试将叙事故事和新闻写作风格融合在一起。它分四部分。第一部分是重点导语，它不像倒金字塔式的导语，可能长达五段。第二部分是结论段，它得名于“简明扼要地”总结故事。结论段陈述了故事的核心部分以及导语如何阐明该观点。
然后在正文中详细阐述核心观点，而结尾以难忘的曲折或评论将故事引向自然结论。我的文章“避免‘成功的灾难：Ticketmaster 之战 Taylor Swift”展示了它是如何进行的，其中结论段出现在第五段，如下以红色标记。
在技术写作中，此风格往往会略微变化，即用轶事或故事作为切入点和引导，然后通过关键段落作为风格化的转折，进而进入文章的核心内容。这种方法之所以奏效，部分原因在于人类天性喜欢故事；在会议演讲中它也很有效，这也是大多数 TED 演讲会以轶事开场的原因。
在 Jennifer Riggins 的“如何纵火烧毁喷子农场”一文中，你可以看到它是如何奏效的。在关键段落充当第四段转折之前，她用三段文字聚焦叙事（如下方的红色边框所示）。
知道何时停止
术语“结尾”指的是故事的结尾。结尾会导致无穷无尽的问题。我认为原因之一是，在学校里，我们被教导文章有开头、中间和结尾，并且结尾应该以更简洁的形式重述我们已经说过的话。
当你把“结论”放在小标题中，或者写一些诸如“总而言之，可以指出……”之类的话时，你就会知道自己在这么做。此时，你的读者会听到你的整篇文章都在吱吱作响。
这样的结论会破坏你迄今为止所做的任何好工作。一个好的结尾应该感觉像是一个自然停止的地方。我使用的一个技巧是回顾我的笔记，看看我是否能找到任何感觉像是结束这篇文章的自然理由。以下是我在 The New Stack 文章“关于 Ecstasy，一种专为云端设计的语言”中的一个例子：
“我们已经进行了大约六年的时间，而我们现在才开始构建我们打算构建的实际项目，”Purdy 说。“这是你听说过的通往最小可行产品的最漫长的道路！”
现在我已经介绍了基础知识，请查看本系列的第二部分，了解有关完善你的作品和吸引读者注意力的提示。