前言

这篇推荐给想做好documentation，但却常常失望於document不知道要怎麽解决outdated问题的，或者怀疑人生到底该不该做的人。

这篇不会跟你讨论怎麽写好的document，而主要是探讨document的目的是什麽。

演讲总结

通篇文章不是在讨论怎麽写document，而是在讨论我们为什麽要写document？

首先讲者想跟大家讨论一个主题：到底需不需要documentation？这个问题会浮起在於：

1. 第一，根据敏捷开发宣言，似乎documentation并不那麽重要。

   Working software over comprehensive documentation — Agile Manifesto

2. 第二，大家常常会有一些迷思：document一下就outdated了，写干嘛？我在写扣就是在写document；document是要写UML吗？

以上种种原因导致大家对写document到底有没有意义这件事存疑。

讲者说了其实她也无法帮你回答这个问题，因为其实还是很看状况。所以讲者整篇是想聊聊：「document的实际能带来的效益与用途为何」？尔後你便可以自己思考在你的状况下是否需要documentation。

首先必须要确定的一件事情是：**绝对不要为了流程而去写document。**这是什麽意思？例如你写document只是为了让你老板知道你有在做事。或者你也不知道为什麽要写，只是因为这是开发流程一部分而已。

写Document的目的

再来讲者列出了五点写document的目的：

1. 创造共同的理解
   人脑不像电脑，即使同一句话在不同人脑袋里都有不同的解释，所以document一部分的目的就是让大家取得共识，确认大家的理解是相同的。举例来说会议记录（meeting minutes）就是个很常见的为此目的而诞生的document。

   讲者讲到一个有趣的练习是，你可以先讲一个概念给整个团队，然後大家分别回去写下自己的理解，而後来看大家的理解是否相同。这个好处是你可以知道谁的思路可能比较不一样，或者你讲解的方式是不是大家都能有相同的理解。

   另外讲者也讲到一个叫共同理解墙的想法，就是可以把这些大家已经确定取得共识的讨论画成图放在墙上，以便大家随时都可以看到，也可以让新人快速融入。

2. 理解复杂的问题
   对於复杂或不直观的事物，我们必须要记录下来，为了提醒未来的自己或帮助他人理解这个复杂的东西。而如果它是有一些重要的历史演进过程的话，也必须要跟着记录下来，因为很多时候人们会无法理解为何现状是如何，所以必须要花点心力把迭代的过程与原因也写下来才能帮助理解。

   讲者说在他们团队里也会把一块一块系统component画出来变成widget，最终这堆widgets可以变成widget kits。当他们想还原某个系统的演进过程或讨论时，就可以把这些component拿出来用。

3. 创造同理的环境

   • 像上述写的就是技术决策者去同理工程师们，记录做决策的原因帮助他们理解缘由。

   • 工程师也要去同理工程师。

     有人叫这个「同理优先开发（Empathy Driven Development，sorry我真的不知道怎麽翻译这个XD）」，就是你要写出有同理心的code，记录一些comment，或提供一些背景知识。因为有句话说「没有引导跟文件的软件开发，就是在散拨焦虑」，而这件事特别发生在senior对待junior的沟通上。

   • 工程师也更要同理产品人员。

     而工程师虽然常常抱怨产品经理（PM）：根本就不懂软件，或写的需求文件很烂。但其实我们也没花很多心力去尝试让PM理解软件，或者我们自己写的document也不怎麽好理解。

   • 工程师也必须要同理其他外部技术人员。

     我们外人看都觉得别人做的事情很简单，但你又没亲自做过你们怎麽知道到底是真的很简单还是有很大部分事情你没看到。

4. 帮助未来的自己做决定

   上面也讲到写document很大一部分是帮助未来的你了解过去的context，以便你有更多的资讯量帮助做出更好的决定。很多时候我们会遇到一个问题是，不清楚当初做决策的原因是为何？所以导致我们也有两条路（1）盲目的继续接受这个决策 （2）盲目的改变这个决策。但无论何者都不太理想，所以我们最好还是能好好的把事情记录下来。

   讲者给了一个简单的template我们要怎麽记录决策内容，可以见此范例。有个重点是，一定要把问题写清楚，而不是只写解法，因为我们看得到解法但可能不知原先的问题为何。

5. 帮助解决问题

   当你尝试尝试画出你遇到的问题时，往往能同时激发你的左右脑因而达到找到问题解法的目的。所以某部分的写document是为了厘清思路与帮助思考。而这些docuemnt你也无须留下来，因为他只是帮助你整理思路的一个途径而已。

如何处理document容易out-dated的问题

很多人会觉得这个的解法就是去自动化documentation，但就她自己的经验自动化的document都不是很成功，要马太细，要马太抽象，其实都不是真正有必要记录下来的事情，她也很难从中抓住重点。

她觉得out-dated无论如何都是一种必然，因为所有与软件执行无关的东西，在某种程度上都会out-dated。她列出了几个想法帮助减少out-dated。

1. 越少越简单越好
2. 让docs随处可得
3. 将更新document变成某种仪式。例如每周例会都去看一次需不需要更新。
4. 将更新docs的责任下放给别人，变成一个工作内容。

总结

最後讲者总结了一下就她来说，哪些部分会写document：

1. Code：程序码本身就是documentation
2. Maps：地图来记录怎麽理解整个架构
3. How-tos：记录怎麽使用某些东西（e.g. README.md）
4. History：历史纪录（git history）或者上面说的decision making docs
5. Creative thinking：帮助你思考与寻求解答的docs

而这些的目的都只是为了帮助有效的人与人之间的沟通。回到最初的问题，即使是敏捷开发的流程，你也必须要写docuement。

Do something today that future self will thank you for. — Birgitta Boeckeler

个人心得

自己蛮喜欢这篇演讲的，感觉不少地方也有些共鸣。

我自己是个很喜欢写document的人，因为我喜欢靠documentation来整理我的思绪，document写的好对我来说也是非常大的成就感（就跟写code一样）。但是对於怎麽处理会out-dated这件事情，我也一直没有很好的想法。或许我就是讲者提的那种，写document写久了很怀疑人生到底要怎麽让他保持up-to-date的人。

而且document其实是那种，大家都知道有document很重要，但是大部分人不喜欢写的东西。一部分是其实写document很花心力，但是当资源不足的时候很难投资时间在上面，如果你有时间写document可能还不如多花时间把code写好少出bug或少欠一些技术债。

另一方面是document的discovery也是很困难的事情，虽然演讲中没提到（也不是演讲的重点），但对我来说要如何让大家有visibility知道有哪些东西是被记录下来的其实也是很困难的事情。

关於out-dated

Document out-dated的现象在快速发展的公司特别的明显，常常花费心力写的document过了几个月就整个都不一样了。举个常见的例子是关於我们的产品需求文件（Product Requirement Document，PRD），通常一个feature上线之後会迭代个四五才会比较稳定，但可能半年之内就会一直改一直改，但如果不写一个总的PRD，大家就必须花非常多的时间把每一个版本都从头看到尾才能真的理解内容，这个真的是个非常头痛的问题。虽然我不是PM不是写PRD的人，但是同样状况可以套用在系统架构上，我们之前写的document也是非常容易out-dated，觉得非常苦恼。

虽然讲者讲了一些作法，但我觉得up-to-date还是很困难的事情，特别是当你负责的东西越来越多的时候，的确很难同时维护所有的东西。

同理

我对於同理这部份特别有感触。我觉得大家在写document的时候，我看到的都是「写下我想写的东西」，但其实更重要的是要去想「观众想看到什麽东西」。（前几天有一篇就是在讲这件事：如何写好document）很多junior在写docs的共同问题就是，会写下太多的技术细节，因为写的人往往想的是「我要把document写好，尽量记录的越详细越好」。但一个读者来说，太快进入这些细节却是很容易抓不到重点在哪里，完全无法帮助理解。同样这件事带来的坏处也是很容易out-dated，因为技术细节总是改来改去的。所以写document其实就是一个练习同理非常好的机会。

帮助未来自己

我觉得写文章跟写docs一样，其实都是帮助未来的自己，留下一点思考的足迹，以便你未来回顾与检讨用。这也是为什麽你会看到这篇文章的原因XD。

最後我其实蛮喜欢讲者最後讲的：「Do something today that future self will thank you for. 」。我觉得这件事不只套用在写document，投资自己，或者在做决定的时候，其实都是很好的格言。

作者Birgitta Böckeler是在一家技术顾问公司Thoughtworks的工程师，看了一下她的主页，一样是有蛮多有趣的演讲主题：例如pair programming，怎麽做codebase handover，有兴趣的人可以看看。