浅谈作为程序员如何写好文档：结构化写作

我作为从一名懵懂的实习生转变为工程师的工作经历中，伴随着技术经验的成长，也逐渐意识到了编写文档是知识和经验传递给其他人的最有效方式。通过文档，可以分享我的技术知识和最佳实践，使其他人更好地理解我的工作。在这里，给大家浅谈一下作为技术研发如何写好技术文档

什么是结构化写作？

文档的框架是一篇文档的主心骨，所有的内容都要围绕着这个主心骨所展开，包括标题。运用结构化写作，可以帮助文档搭建一个有逻辑、有条理的框架。这个框架是文档各个部分之间的相互搭配方式，它所反映的是作者写作时的思考路径。

任何事物都有其结构，文档也不例外。

结构是指事物各个组成要素之间的排列，文档中的结构便是指文档中各个信息块的排列。

而结构化写作是指：

• 有意识地理清信息之间的逻辑关系
• 把无序的信息排列为有序的信息
• 创造有逻辑且顺畅的信息流
• 有逻辑，有条理地提炼和组织信息

结构化写作核心：先框架，后细节。先整体，再局部。

为什么要结构化写作？

答：有利于双方清晰思考。

• 首先，可以帮助作者理清写作思路：
  • 帮助作者找出信息之间的关联，并有逻辑的呈现，可以帮助作者在清晰分类的基础上全面考虑问题，找到写作的方向和重点。
• 其次，可以为读者降低阅读成本：
  • 通过简明扼要的信息呈现方式，可以帮助读者快速锁定目标信息，在最短的时间内看清行文结构，获取重点信息和核心观点。

如何进行结构化写作？

1. 搭建文档框架

搭建文档框架，自然应该使用结构化的框架思维。结构化写作的本质就是一种框架思维：

• 结论先行：开门见山，把核心观点或中心思想放在文档开头的位置，让读者一目了然。
  不同于制造悬念吸引读者的小说文体，技术文档写作是为了高效地传递信息，结论先行可以帮助读者快速抓住文档的核心观点。
• 以上统下：以上统下是指上层结论是概括总结，然后再通过下层信息进行具体的解释和说明。
  以上统下的原则可以让我们的文档更有理有据，让内容更具有说服力和支撑力。
• 归类分组：是指把相关联的信息按照一定的标准进行划分，归类归为同一个逻辑范畴。
  在分类的过程中可以探寻事物和问题本质，让原本模糊混乱的信息变得有秩序，便于读者获取和记忆。
• 逻辑递进：按照逻辑顺序递进排列信息。
  梳理信息之间的逻辑，可以反映出事物之间的内在联系和规律。

结合一个实际的例子：需要要写一篇应用上线某应用商店的文档，如何给自己的文档搭框架：

1. 首先，依据结论先行的原则，我们要明确主题，即应用上线某商店，我们将这个主题写在中心位置。

2. 依据逻辑递进的原则，我们要考虑这个任务按常理会是怎样一条逻辑递进的原则。既然涉及应用上线，大致可以想到：

   • 上线必须满足的必要条
   • 上线过程中可能遇到潜在卡点
   • 如何解决这些卡点问题
     

   最后依据以上统下的原则，我们要用下层的信息进一步解释上层的信息：即哪些是必要条件，潜在卡点又有哪些以及可行的解决方案是什么：
   依据这个框架思维，我们就完成了结构化写作的第一步，搭建文档框架。

2. 填充必要信息

信息的收集在数量上要完整全面，在质量上要深入有层次。
我们的信息来源可以是：

• 阅读相关文档
• 使用相关产品
• 咨询行业内的专家

当文档有了初步框架后，可以沿着这个基础框架填充细节信息，让文档的内容更加全面、更加细致。
回到刚刚的例子，依然可以对文档的框架使用以上统下的原则对每一个小点进行进一步的解释说明：

至此，我们成功打好了一个文档的基础框架。

3. 巧用结构化呈现文档内容

结构化思维不仅仅体现在搭框架的过程中，它同时也可以落实到文字的呈现格式上。
这里向大家介绍 3 种最常见也是最实用的结构化呈现方式，这些呈现方式体现了归类分组的思维：

• 无序列表：没有特定的顺序的列表，各个列表项之间属于并列关系
• 有序列表：强调排列顺序的列表，各个列表项之间属于先后关系。
• 表格：一种可视化交流模式，也是一种组织整理内容的手段，主要用来罗列和对比信息。

回到之前的例子，当这些结构化呈现方式从搭好的框架落实到文档之后，文档会产生什么样的变化：

可以看到两篇文档的字数大致相同，但因为使用了结构化呈现方式，文档变得更加清晰精炼了。
我们可以通过扫读获取非常多的信息。但是在结构化前，大量的重要信息被淹没在了大段的文字中。读者必须通过逐字逐句地仔细阅读才能获取重要信息，其主要原因还是没有将同类信息进行分类，导致信息杂糅在一起。

总结