原文：Writing for Engineers —— Stemwede, 2022-04-15
写作是在大型组织中产生影响的关键。作为一名高级软件工程师，写作有可能是你必须掌握的最重要的技能，以扩大你在团队以外的范围，并推动你的职业生涯。
写作是很难的。许多软件工程师都在为写作而奋斗。就我个人而言，我对文学从来没有内在的兴趣，所以写作也不是自然而然地出现在我身上。我曾经花了几天和几周的时间，围绕着较大的写作任务而苦恼和拖延。而且直到今天，在截止日期前制作高质量文章的压力也经常让我做噩梦。
这篇文章包含了在过去 15 年里帮助我（和其 TA 人）成为更好、更有生产力的作家的一些经验。我分享这些经验，是希望你能发现它们的作用。然而，不要以为我自己总是能够遵循这些建议😅。我还有很多东西要学。
在开始写作之前
你得有话可说
这句话似乎很明显，但结果却经常出现问题，这很令人惊讶。写作的目的是以有效的方式向受众传递信息。如果你没有一个好的信息，你将很难写出有用的东西。
在大学期间，我曾多次被要求为欧盟项目撰写长篇报告文件。这是很糟糕的经验，因为主要的目标是要好看，要写满几页。一般来说，我对这个领域有一个很好的想法，但没有一个明确的信息或足够的深度。对我来说，这使得我很难写任何东西。现在想来，我觉得 GPT-3 在写欧盟项目报告方面会很了不起。 我最成功的一篇 [博文](blog posts)（导致了 一系列 关于这个主题的 会谈）是在酒店房间里花了 3 个小时写的，第二天就发表了。这是我在同一天与几个谷歌 SRE 在 SRECon EMEA 2018 进行的讨论的后续。我知道我想说什么。我知道我想接触的人。这使得写这篇文章变得非常容易。
如果你脑子里没有一个明确的信息，你还没有准备好开始写一篇叙述。你还有其他事情要做。研究主题，找到你的信息。重要的是要认识到，这些是不同的任务。它们可能涉及到以笔记或日记形式的写作，但这不是你在最终文件中直接使用的材料。
不要混淆写作和学习
意识到你脑子里没有完整的信息，往往只有在写作时才会变得明显。这表现为无法找到一个好的突破口或无法清楚地表达自己。事实上，写作是一个很好的测试，可以看出你是否对一个主题有很好的理解，并对该领域的词汇有牢固的掌握。有一句话是这样说的：写作是上帝向你展示你的想法是多么不完美。
与此类似：一旦你说出来，一个论点就只有一半好。
如果你遇到这个问题，这意味着你正在学习东西。一般来说，写作是一种很好的学习方式，但人们必须意识到你正在做这件事。学习是一个缓慢的过程，需要耐心。在屏幕前苦苦挣扎，试图挤出另一个句子，这对学习没有多大帮助。通过阅读书籍、博客或论文对该主题进行更多研究，并做笔记可能是更好的时间投资。
了解你的听众
你越是了解和理解你的受众，就越容易达到向他们传递信息的目的。文本的目标受众影响着你可以使用的术语，你可以假设的背景和写作风格（休闲/正式）。
在写一篇文章时，我一般会把一个具体的人想象成我所要引导的受众的代表。这通常也是第一个人，他将会得到一份阅读草稿。一般来说，“对人” 讲故事要比对着虚空说话容易得多。
我在这个博客上的大多数 #math 标签的文章实际上都缺乏好的听众。它们只对精通抽象数学的人有可读性，但只对从事软件工作的人感兴趣。这两个群体的交集是很小的。因此，我不指望那些人有很大的共鸣或影响。它们记录的是我自己想学的东西。
尊重你的心态
写作需要长时间的高度集中。理想情况下，你要进入一种流动状态，在这种状态下，你会全神贯注，连续几个小时都在写文章。这是迄今为止写记叙文或博客文章的最有效方式 —— 至少对我来说是如此。
为写作任务做好准备，就像你要去爬山一样。你是在磨练。找一个舒适的空间坐下。带上你喜欢的饮料/小吃。最重要的是，要确保你休息好了，能够集中精力。不要在你已经很累的时候开始写作任务。你不可能写出任何有用的东西。
此外，尽可能避免分心。最重要的是。把聊天的声音关掉。在你的日程表中至少留出 3 小时用于写作。如果我为工作而写较长的文件，我会尽量安排一整个下午。对我来说，最有效的写作时间是在周末或假期，因为我根本没有任何会议。
趁热打铁
就像编程一样，写作需要你在短期记忆中保留大量的背景。你需要回忆起关于你所写的主题的很多细节，以及你的重头戏和文件的当前状态。所有这些状态都需要时间来加载到记忆中，而且很容易因为分心或上下文切换而丢失。
如果你在任何特定的时间点，在你的大脑中加载了很多有用的上下文，那么就利用这些上下文做一些有用的事情。试着利用这一时刻，当你意识到你有能力有效地写出你的主题时，就可以腾出空间。
在工作前将铁加热
相反，如果你现在脑子里没有上下文，你有两个选择（1）不写，或者（2）开始把上下文装进你的大脑。
缺少上下文是痛苦和拖延的一个经常性来源。不要指望从你的清单中拿出一个像 “写会议发言” 这样的 TODO，然后马上开始工作。在你有机会写出哪怕一个句子之前，你需要投入时间来加载上下文。
装入一些背景的好方法是：
- 翻阅你关于这个话题的笔记。
- 与同事 / 随机的陌生人 / 家庭成员讨论这个话题。
- 阅读一些关于该主题的书籍 / 博客 / 论文。
装入背景的坏方法是浏览 HackerNews 或 YouTube。
在写作时
从最重要的开始，而不是从头开始
这是迄今为止我看到的人们所犯的最常见和最有害的错误。他们从叙事的开头开始写。
“很久很久以前，在一个遥远的星系中......”
你真的认为这些是乔治-卢卡斯在写最初的《星球大战》三部曲时带到纸上的第一个词吗？
对于超过一页的文件，你必须采取自上而下的方法，从大纲开始。大纲是一个章节的清单，加上粗略的注释，通常以要点的形式。对于这份文件，第一个大纲看起来像这样：
# 如何写作？
- 受众：高级 SWE 及更资深的人员
- 目标：提高技能，解除写作障碍
## 有话可说
- 目标：将信息传递给受众。
- 没有信息的写作是痛苦的。从石头中挤出水来。
## 了解你的听众
## 趁热打铁
- 注意你的大脑环境
- 如果你有正确的语境，就能开始/保持工作状态
- 在你开始之前加载上下文
## 将编辑、出版和写作分开
- 如果你在开始写作前摆弄 git/emacs。你就做错了事。
...
请注意，这些章节的标题不只是一般的脚手架（如 “介绍” / “主体” / “结论”），而是已经说明了整个故事。
在充实内容之前先解决故事线的问题
在建造房屋时，你要先完成砖头工程，然后再涂抹油漆。写作时，在开始充实和润色文本之前，你要为你的文件达成一个好的故事线。大纲应该是你所写的任何大型文件的第一个里程碑。大纲应该传达主要信息，并提供一条清晰的 “红线”，引导读者了解你的论点。
在 一家咨询公司 工作时，我看到我的高级同事在处理细节问题之前，花了很多时间来打磨和迭代他们的幻灯片结构。他们会把幻灯片打印在纸上，把幻灯片钉在墙上，然后不断地重新排列，直到他们对故事线感到满意。幻灯片会一直挂在墙上，并被重新排列，直到幻灯片最终完成。
一旦你已经充实了段落，修复文件的故事线就会变得更加昂贵。在某些情况下，你能做的最好的事情就是把整个内容藏起来，在重新建立文件之前回到大纲中去。
在开始润色之前先完成内容
我曾多次发现自己陷入一个陷阱，就是被那些不需要制作叙述的相邻任务所干扰。这些任务包括：
- 编辑：修正拼写、措辞或调整段落结构。
- 发布：摆弄格式，调整 WordPress，使你的 git + hugo + heroku 部署自动化。
- 制作图片：在纸上画草图，或浏览网络上的图片，以便在你的演讲中使用。
记住：你的文件的第一个里程碑是一个纲要。所有不直接有助于实现这一目标的东西都是分散注意力的。
当你对大纲感到满意时，第二个里程碑是一个完整的文本，所有的注释都被转换为段落。该文本应涵盖预期的内容，但不需要精炼或写得很好。
一旦到了这一步，你就可以开始去操心润色的问题了。删除错别字，改进措辞，调整段落结构。另外，关于数字和出版的工作可以推迟到这一点，不会有任何问题。
让你的文字可以略读
根据互联网上 某人的说法：
八秒。一个网站用户的注意力在 8 秒左右。
在这八秒钟内，你的文件必须向用户揭示足够的价值，使他/她愿意投入更多的时间来实际阅读该文件。
如果你想让别人听到你的声音（同时提高你的文本的 可用性），你必须设计你的文件以实现 “略读性”。要做到这一点，你要提供锚点，使用户能够在不实际阅读的情况下衡量内容。你希望大纲和关键论点在文件的最终版本中保持突出地位。
章节标题和列表是你想用来达到这一目标的关键锚点。另外，数字、引言和重点也是在略读时突出和抓住注意力的特征。
如果你正在写一个幻灯片，一个很好的方法是使用 “行动标题”（Action Title）来确保可读性。行动标题是用一个完整的句子来概括幻灯片的内容的幻灯片标题。通过这样做，你可以让读者仅通过阅读标题就能了解你的文件的要点。互联网上这个非常令人讨厌的家伙在 这里 很好地解释了这个概念和围绕它的想法。
提供摘要部分
摘要部分通常出现在文件模板和学术写作中。它们是可用性特征，为匆忙的读者提供关于内容的高级概述。预计你的大部分读者将只阅读摘要。
- 摘要 / 执行摘要 / TL;DR：这一部分总结了文件的内容，故意重复了信息。它通常是你文件的第一部分，是为尚未阅读文件的读者准备的。一个好的摘要描述了背景，激发了问题，总结了结果，但也留下了一些悬念，以激发进一步的阅读。
- 结论：这一部分也是对内容的总结，因此与摘要相似。不同的是，它是你文件中的最后一节，侧重于结果，并刻意回溯到内容。其基本思想是，读者在到达这里之前已经阅读了文件，但实际上几乎没有这种情况。
值得注意的是，这些摘要部分是独立于故事主线的，因此是一个可以独立准备的艺术品。一般来说，我建议最后才开始做摘要部分（如摘要/结论），因为只有到那时你才能确定你的文件到底涵盖了什么。
写作的练习
持续写作
提高写作水平的唯一途径是写作。与一般的练习一样，重视数量而不是质量通常是一个好主意。培养写作能力，每周写一些相对较短的中等质量的文件，将使你成为一个更好的作家，而不是每年写一次高度精炼的文件。
我在学校的英语老师曾经说过。“写作。只有写作才能带来福气”。我没有多想这个口号，但它足够吸引人，让我记忆深刻。现在我认为这是一个深刻的真理，并把它放在我博客的顶部，作为一个提醒。
利用小型写作任务作为练习
大多数适用于写长篇文档的规则，如技术叙述、博客文章或论文，都适用于写短篇文档，如电子邮件或问题单。使用这些文件来练习你的写作技巧，使它们结构良好，可用和有光泽。
尽早获得对你的大纲的反馈
一旦你构筑了大纲并完善了故事线，你就可以对你的文件获得初步反馈。这可以让你尽早发现故事线的缺陷，并确保你的内容是有针对性的。另外，阅读大纲是一件非常快的事情，所以你的审稿人不需要花很多精力就能看完你的文本。
这对你应利益相关者（经理）的要求制作的长篇文件来说是最重要的。
向选定的听众分发文本的草稿
一旦你充实了内容，并做了第一次编辑，删除了最明显的语法和拼写错误，你就可以把文件发给几个选定的目标受众成员。
这种做法有三个好处：
- 你会得到一双新的眼睛，至少可以捕捉到文本中残留的一些语法错误。
- 你从自己的文本工作中抽身出来，直到收到反馈，让自己重新审视自己的写作。
- 你有了一个借口，可以与被你忽视了很久的老朋友们联系。
致谢
感谢我的姐姐 Johanna Hartmann 和 Andrew Howden 对本文早期版本的反馈。
