原创 如何写好技术问题的说明文件

最近一段时间，经常与PPT文件为伍，开会的时候也是较多的涉及文件，因此有了一些来来回回的修改，此篇做一些整理，作为以后写类似文档的参考。

1.区分对象

    个人感觉，最大的问题其实是区分说明文件的受众。基本上，类似于我们这一级的工程师，是需要把自己面临的技术问题，以较为通俗化的描述方式反馈给我们的技术“老大”，而“老大”获取这份文件，往往并不是终点，还得进行上一层的传递和表达。某些时候，这些文件，也是需要给客户的工程师或者他的Boss，来说明某某事情的问题。

   因此，写此类报告，往往需要有几点要求：

a.足够短，足够精悍

   因为越往上，可能花在此事情的时间越短，所以得花较短的篇幅，花其中最重要的点表达出来。

b.足够的背景说明与辅助文件

   文件需要保证能够在不补充的情况下，没有基本知识背景的条件下，能够有75%以上的认知。而需要工程师自己准备一些说明材料，以最短的时间，大概整理给老板，以便于其向上整理。

c.每个词精确

   已经有几任老大都觉得这是必要的，在本身篇幅较短的时候，用词不准将会导致歧义等，将会使得事情变得非常糟糕。所以在做完内容，经过若干检查后，对文辞的检查是非常重要的；需要特别注意的，还是基本英语的学习，虽然大多数人都似乎关注口语的表达，但写个简单的文档漏洞百出，结局会更惨。而且在小会议厅里头，老板找你逐字逐句帮你挑错误，是何等的尴尬啊。

2.实际操作中的准备

   在实际操作中，往往都是接到一个任务，比如老板希望把你某段时间中所遇到的问题，以及某个项目中的Issue，以总结的概念整理出来。往往是作为其概述的一部分，因此需要注意几点：

a.确定内容和范围

   与其在交代不清的前提下，死命整理材料，然后收获糟糕的评价，还不如耐着性子，把要求仔细的分辨出来。这里就存在内容损耗和偏好问题，在确认足够的清楚的条件下，整个文件最终的误差会在许可的范围内，或者可以经过较小的修正就可以完成了。

b.屏蔽技术细节

   我经常犯的一个错误，就像写博文一样，把足够多的细节都整理出来了。脑海之中的问题，往往是个人的思维结果，一般而言，旁人是需要花很多的时间去学习的，特别是离细节较远的老大们。这里就需要做足够的功课，把技术的细节，以一种相对易懂的方式整理出来。目前理解的时间分配，可能需要60分钟准备基础材料，得花更多的时间进行加工，最后检查也要留有足够的时间。

  写这篇的内容，主要是自己这段时间确实做得有些糟糕。从思想上，从技术上都受到了很大的打击，可能工程师们总以为说明的事情是相对容易和幼稚的活，但是糟糕的表达和沟通，基本就限制了项目的效率。

  文章写到这里有些乱，先作为初稿吧。