为软件工程师写作：超越基础
一旦你开始写一篇文章或博客文章，如何润色它才能让读者渴望阅读它？在我们的系列文章的第二部分中获得一些提示。
译自 Writing for Software Engineers: Beyond the Basics，作者 Charles Humble。非常棒的写作教材，之前另一篇是陈皓老师翻译的《Google 技术写作》，也在这里缅怀一下陈皓老师。
如果你为互联网写作，大多数人在决定是否点击并阅读你的文章之前唯一会阅读的内容就是标题。一位优秀的编辑可以帮助你解决这个问题，我坚信这是他们的责任，但如果你尝试自己想出标题，一个好的测试方法是问自己，“在没有上下文的情况下，我会阅读这个标题吗？”
例如，像“监管机构会喜欢你”这样的标题可能不起作用——它是什么意思？一些更好的标题：
一旦你的文章从网站首页消失，你的几乎所有流量都可能来自 Google 搜索——标题可能是你的读者在决定是否点击它之前唯一会看到的内容。在你的标题中使用读者可能搜索的单词；注意在我的示例中使用了 Svelte、Web 框架、TypeScript 和 JavaScript。
这自然会引发对搜索引擎优化的讨论，但 SEO 是一个如此庞大的主题，我不会在这里讨论它。专注于尽可能地制作出好的内容，并相信如果内容好，Google 会找到你。
写作技巧
解释术语，拼写缩写
正如我在 第一部分 中提到的，考虑你的受众是否可能不熟悉这些术语非常重要，如果是，请提供链接或定义。
一个相关的风格要点是一致性。如果你在方法中程更改变量的名称，你的代码将无法编译。如果你在段落中程更改你使用的术语，信息将无法为你的读者编译。因此，如果你将某物称为 Protocol Buffers，请不要在介绍缩写版本之前将其重命名为 Protobuffs：“Protocol Buffers（简称 Protobuffs）”。
同样，在首次引入缩写时，拼写出完整术语，然后将缩写放在括号中。此后，你可以使用缩写。例外情况是缩写是众所周知的。你可能不需要解释 RAM 或 HTML，但你可能想在首次提及时拼写出安全软件开发框架 (SSDF)。
保持简单
William Zinsser 写了我最喜欢的关于这个主题的书，“写作技巧”，它真的帮助我理清了如何清晰简洁地写作的思路。我深深感谢他，我将在本节中分享他的信息。
他使用的一句话让我印象深刻，“写得好文章的秘诀是将每个句子分解成最简洁的成分。”
我们作为工程师不喜欢这样。我们倾向于让事情听起来过于复杂，这样我们才能听起来非常聪明和非常重要。为什么称铁锹为铁锹，而你可以称它为“用于挖掘的翻土园艺工具”？为什么说要下雨，而你可以说，“我们目前预计会有大量降水”？
保持简单的原因是为了尊重你的读者。
在技术、更广泛的商业领域以及政治领域，经常使用文字来给人留下深刻印象或混淆视听，而不是解释。破产的公司发现自己处于“现金流为负”的状态，或者飞机没有坠毁，而是“发生了非自愿故障”，等等。
不要这样做。像对待代码中的方法一样，尽可能干净地写作。
对于非虚构写作，你的目标不应该是炫耀你的词汇量有多丰富，而是尽可能清晰地传达含义。这是一项艰苦的工作；一个清晰的句子不是偶然的。欣赏好文章的人会理解创作它的工作。
我特别喜欢过度使用限定词。去掉它们。与其说“有些人认为 Kubernetes 在某些情况下可能被认为过于复杂”，不如说“Kubernetes 很复杂”。正如津瑟所说，“好的写作精炼而自信。”
删掉小词。我发现它“有一点”让人困惑；我“有点”生气。困惑吧，生气吧。避免使用“轻而易举”——如果轻而易举，那就是毫不费力的，那就用“毫不费力”。
修剪形容词——大部分都是不必要的。你不需要告诉我水仙是黄色的或者土壤是棕色的；我能猜到。当然，如果土壤是蓝色的，那会更值得注意。
如果某事值得一提，那就让它读起来有趣——不要告诉我它有趣；向我展示它有趣。
让你的文字读起来有吸引力
写作是一种视觉媒介，在进入大脑之前就会吸引眼球。短段落使你所写的内容看起来有吸引力，而一大块文字可能会令人反感。
当然，这里有一个权衡。一系列小段落和一段太长的段落一样令人讨厌。我编辑过完全由单句段落组成的文章。避免这种情况。我会说，对于报纸来说，一个好的默认值是大约三句话，对于博客来说，大约是四到五句话。但要改变长度。
在每个段落中，注意句子是否太长。如果你发现自己在长句中迷失了方向，你可能试图表达太多想法。摆脱这种情况的一个快速方法是将其分成两句话，甚至三句话。
看看你是否可以通过颠倒句子的顺序、替换一个新颖或不寻常的词，或改变句子的长度来增加多样性，这样它们就不会听起来都一样。
有时，解决棘手句子的最佳方法是摆脱它。这似乎总是你想到的最后一个选项；如果你发现自己在与重新表述或澄清句子作斗争，那么没有它你可能会更好。
节奏和押头韵等文体技巧很有帮助。出于这个原因，我鼓励你大声朗读你所写的一切。我完全凭耳朵写作，并在发布之前大声朗读所有内容。
使用可用工具
在第一部分，我提到了我的软件工具链（Mac Pages—> Google Docs—> Docs to Markdown）。我通常在文本编辑器中编辑 HTML 和 Markdown，但有时会使用 Dreamweaver 或 Caret。我不做很多图像工作，但我使用 Pixelmator Pro 进行插图。
我通常在 Zoom 上远程进行采访。通过使用其内置的音频录制功能，我不需要依赖我糟糕的速记。对于面对面的采访，例如在会议上，我随身携带 Zoom H4N Pro，我已经用了很多年了；这是一款很棒的产品，但你可能只需要在手机上使用一个应用程序。
由于技术可能会出现故障，我还在手机上运行备份录音。我仍然手动转录采访中的引语，但许多作家使用语音转文本转录服务，例如 Otter 或人工支持的 Rev 来完成繁琐的工作。
我认为当今大多数作家都在关注大型语言模型 (LLM)，并想知道它们是否可能有用。我曾对它们进行过试验，但没有发现它们有帮助，因为它们产生的文本过于通用且容易出错——相当于 Muzak 的写作，或者正如顾问 Mark Hurst 所说，Polyfilla/spackle。
鉴于它们的道德基础不稳、环境成本以及幻觉和抄袭的危险，我认为 LLM 目前带来的风险大于其价值，并且不会在写作中使用它们。The New Stack 不使用人工智能 (AI) 生成的文章，并已就此发布了其政策，值得一读。
除了软件之外，任何作家的主要工具都是一本好词典和一本同义词典，你可能会发现语法指南很有帮助。除了 Zinsser 之外，我还推荐阅读 Jon Franklin 的“Writing for Story”和 Lynne Truss 的“Eats, Shoots & Leaves”。在第一次新冠封锁期间，我和我最大的孩子（一个有抱负的小说家）一起参加了 Neil Gaiman 的大师班学习讲故事的艺术，我们都非常享受。
我这里没时间深入探讨 SEO 方面的问题，但是，如果你对该主题感兴趣，我发现“Google 时代的营销”很有帮助；它现在有点过时了，但核心建议是可靠的。权威的 SEO 指南是 Eric Enge、Stephan Spencer 和 Jessie Stricchiola 的“SEO 艺术”。
我强烈建议，如果你找到了一个你钦佩其作品的作家，那么看看你是否能够模仿他们的风格；你会从玩弄其他作家的技巧中学到很多东西。
最终，写作就像编码一样，是一种解决问题的方式。挑战可能是获取事实、组织材料或语调或风格。一些模式和结构可能有帮助，但是，与编程一样，你也会随着实践变得更好。