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