前言

（因为最近时间有点少XD，所以偷偷选了比较短的影片来硬塞XD）

这篇显然就是个蛮一般的topic，所以大家都可以看XD。如果你每次document都写很长，但是读者却总是抓不到重点，一直问你问题的话，那你可能可以考虑看看这篇。

演讲总结

写文件（documentation）在业界是至关重要的，讲者分享了多年写document的经验，列出了五项写好文章的重点：

1. 从读者的角度出发：

   写document的目的并不是为了「记录我的技术」，而是为了「让读者来使用」。所以你要先想，读者到底想要获得哪些讯息？举例来说，如果你要写个user guide，你就不该写太多关於design细节的东西，因为reader可能根本就不在乎。

2. 写越少越好：

   写太多细节其实会造成你必须要去频繁的更新，相信大家都有遇到写document没空更新的状况。所以说，练习点到为止，写到你未来有余力去更新的深度就好。

3. 先写大纲：

   如果你不知道文件要怎麽写，你可以先可以先列出些你想回答读者的问题，用条列式，然後再填入细节。这样的好处是确保你可以达到上面说的第一与第二个原则。

4. 使用小黄鸭工作法：

   这源自於小黄鸭除错法（Rubber duck debugging），意思是当你找不到bug的时候就跟小黄鸭一行一行解释，然後你自然就会找到debug的灵感了。同样的，当你不知道怎麽用文件阐述某件事情的时候，你可以练习用小黄鸭工作法，通常这时候你讲出来的内容就会是最好的文件阐述方式。讲者讲到其中一个原因是，我们在写文件的时候往往会倾向写的「正式」，但是读者其实对於理解正式的描述并不见得擅长，相对来说，非正式的表述往往较浅显易懂。

   Insights are often found by simply describing the problem aloud.
   — Duck, Quack Overflow

5. 强调可读性：

   这里指的可读性是说，你可以利用排版、粗体、分段、列点、颜色各种方式来增加可读性。而不会让读者看起来是在读一个文字墙。而这技巧其实不只用在写文件上，任何沟通的文章都是。

   讲者也讲了一些写作小技巧，例如句子不要超过25个字，一段话只阐述一件事等等。有兴趣的人可以自己看她的blog文章：Editing。

最後讲者提到，写文件只能帮助发掘问题，但不能真正解决问题。往往你在document过程中会发现一些问题。可能是写作流程上过於繁琐，可能是某个概念非常难以解释，无论你发现的问题是什麽，更重要的其实是解决这些问题，而不是写文件去记录这些问题。

个人心得

我自己是个很喜欢写文件的人，主要原因是因为写文件可以帮助整理思绪，写完之後，也会觉得非常有成就感。其实写文件其实就跟写code一样，要写完不难，但要写好真的需要花很长时间练习与适应，就像讲者说的，重点不是你想表达什麽而是读者想知道什麽，所以理解读者的需求其实也是写文件很重要的一环。

下面我列出一些个人读後心得。

Rubber duck debugging我也是第一次听到，但觉得这真的超真实的。自己也是遇过好几次脑中自己想code都没问题，但一跟别人解释就很容易自己发现不对劲，然後就找到bug了。

至於正式的表述这件事，我自己是觉得还是要看情况，有些人的document写的太过口语导致读者抓不到重点。就文件来说我觉得精简还是有必要的，只是在精简的同时，可以少用些不太常用的单字，可以让读者读起来轻松一点。拿新闻来比喻的话我自己觉得NYtimes的用字就比起Washington Post难懂很多XD。

可读性这里蛮酷的，因为我自己也是很无法接受文章一堆文字的状况，所以自己在写文章的时候就会尽量的用格式化的方式让他看起来更佳易懂。她的blog文章写了不少关於写作可读性的点，强烈推荐有兴趣的人去看看：Editing。

（图片来源：撷取自原演讲投影片）

我其实对於讲者的职业蛮有兴趣的，她的title是Technical writer，我原本也从来没想过世界上有这样的职业，但因为我们团队其实有一波讨论要找technical writer，帮忙写一些内部技术沟通与分享的文件，我才想到这个真的是可以成为一个职业的。

可能很多人会问说，document不是工程师自己写就好了吗，这不是个好的工程师的必备技能吗？我自己对这个问题的答案是：文件的确是工程师要自己写，也是个工程师该训练的技能，但不代表公司不该请专门的人来做这件事。自己想到的原因有几个：

1. 每个人训练写文件要时间，不见得有时间等每个人慢慢成长把文件写好。
2. 文件作为一个沟通工具，如果大家都照自己的想法去写跟画架构，对於读者来说必须要理解每个人的写作习惯也是件很困难的事情。所以如果能限缩需要同步写法的人在一定范围内，相对来说文件的一致性也能提昇，对读者来说也能提高可读性。
3. 如果内部文件还好，但如果是外部的话可能就更需要这样的人存在，因为要有人负责去过滤与修饰使用的文字，毕竟外部文件对公司而言也是非常重要的公关。