工程师该如何写好文件?

软体工程师除了要写好程式，也需要会写作。先前 Meta 的主任工程师 Ryan Peterman 曾经发过一条推文，内容写说最重要的语言不是 Python、C++、Rust 或 Java，而是英文，因为软体开发是需要大量合作的，而写作在这个过程中，是高频率会被用到。

具体来说，技术设计文件、技术会议讨论、程式码审查 (code review) 等等场合，都是需要写作。当然 Ryan Peterman 提的英文可以替代成其他的自然语言 (例如我们使用的繁体中文)，不过核心概念不变，写作能力提升，对软体工程师的职涯帮助会很大。

为什么要写文件? 有什么好处?

在谈如何写好文件前，想先谈一下为什么要写文件? 写文件有什么好处? 很多人会觉得写文件是种麻烦，所以会倾向不写；但如果能理解写文件带来的好处，提升自己去写文件的意愿，长期来看对职涯会有帮助。

先从个人的角度来看，对个人而言写好文件的杠杆很高，因为：

写文件时，能帮助自己想得更清楚：很多关于技术设计的想法，比起在脑中想，写下来的过程，能帮助自己思辨地更透彻。
让影响力能扩大：很多事情能透过文件化来节省时间，举例来说，假如要教导团队中的新成员，没有文件下，可能每次有人入职就要重复教一次。当有文件后，可以让新成员直接看文件，这时就能用 O(1) 的成本来协助未来所有新成员理解某个概念。
在升迁时能被看见：Walmart 的资深工程总监 Louie Bacaj 先前分享过，写好文件对升迁的帮助，并不亚于写好程式码。当你写的文件被许多人阅读，并能有效帮助团队成员学习某个概念，这会对升迁非常加分。

对团队与公司来说，写文件的好处也很多

确保关键知识不会遗失：很多时候，随著有人离职、团队改组，很多关键知识会遗失，这要去找回来可能成本很高，如果有文件化，就能免去这些成本。
资深成员的时间可以被释放：从团队生产力的角度来说，如果某个问题被问第一遍时还没有文件，这时如过已经可以预期接下来会有其他人也问同样问题，那就是该写文件的好时机。因为当这时有文件，资深工程师就可以省下解释的时间，去做其他更重要的事。
新团队成员可以独立运作：许多新团队成员，可能会担心太过频繁找人问问题，会打扰到别人，虽然如果在一个健康的团队中不该有这种担心，但更理想的状况是，团队文件化够好，让新团队成员可以直接独立运作。

程式码写好，不代表不用写文件

读完上面的这些列点，有人可能会说，假如程式码写得够好，是不是其实不用文件? 毕竟如果程式码写得够清楚，新成员直接看程式码就能看懂，那样有文件似乎是多此一举?

从实务的角度来说，程式写得好不代表可以不用文件。这是因为在维护者读程式时，能读到程式被怎么写，但是读不到程式「为什么这样写」。而技术文件的用处，很大一部分是在讲解「为什么」。

举例来说，在技术设计文件中，要去写相关的技术取舍，要说明为什么选 A 技术，而不是 B 技术，背后的考量是什么。当有了这些纪录，未来要维护的人，不会看到程式码时就直接说「先前的人是在干嘛，为什么要这样」，而是可以透过文件，去掌握脉络，这样也会让维护变得更轻松。

写文件前需要先思考的问题

在开始写作前，推荐读者们需要先厘清一些问题，这样才会让写得内容更有价值。

了解文件的读者是谁

首先，写作时最重要的事情，是要知道写给谁读。以技术文件来说，是写给同组的工程师、写给别组的工程师、写给没技术背景的产品经理，给这些不同角色时，写的方式会很不一样。这是因为不同读者有的背景知识与脉络，很可能是不同的。假如对于脉络不熟的读者，你写得很简略，对方可能看不懂；对于已经有足够背景知识的，你再写出这些脉络，就显得浪费篇幅。

如果是写给相对缺乏技术背景的读者，请务必确保有提及相关脉络，这样读者才能懂写得内容的重要性。举例来说，假如在技术设计文件写了目标是「把网页的 LCP 优化到 1 秒内」。这句话对于不懂 1 秒内代表什么 (例如业界基本是 2.5 秒，1.5 秒是特别优秀的表现，那这样读者读到 1 秒，就知道这很不容易)。

当然，有时候读者范围很广，所以补充的资讯，可以用外连的方式，放上超连结，让有相关知识的读者不用在文件中读，而没相关知识的读者，可以透过外连去读到。

什么是「最重要的讯息」

在厘清完读者是谁后，接着要想「什么是对读者最重要的」，或者可以思考「读者期望从文件中获得什么」。

一般来说，会读文件的人，多半是遇到问题想要找解答。所以可以回过头思考，对方的问题是什么? 你在解答什么? 想清楚这点，就能更加确保写出来的内容对读者有价值，可以避免人家读完后觉得浪费了自己的时间。

假如你觉得有很多资讯想传达，有个推荐的方法，来帮助自己收敛出最重要的讯息。可以试着思考「如果只有一分钟能跟读者说，你会选择说什么?」或是「如果只能提三件事，你觉得有什么是读者一定要知道的?」。

透过这些问题来有效收敛，能更帮助你传达最重要的讯息。

不同的文件有不同着重面向

前面有谈到，在写文件时，要知道是写给谁看，以及对读者来说什么重要。事实上，不同类型的文件与分享，即使给相同的读者，也可能有不同的着重面向。

具体来说，同样是写文件，以下三种类型文件的着重点会不同：

技术介绍：着重分享这个新技术是什么 (What)，让人快速理解某个新技术在做什么
技术深掘：着重分享背后的原理，不停留在表层，会深掘为什么 (Why)
专案总结：着重分享如何做到 (How)，让未来的人不会犯同样的错

在写文件时，要厘清自己是写哪种文件，放对着重点，这样读者读到的才不会与预期有出入。