软件工程师为什么要写文档

软件工程师为什么要写文档

01

为什么需要写文档？

为什么会做出这些设计决策？

为什么要以这种方式实现这段代码？

为什么大多数工程师不喜欢写文档？

很多工程师习惯将写代码和写作割裂开，不仅仅是在工作上，而且在思想上就认为它们是完全不相关的两项工作，这就导致好多人重代码不重文档。

也有很多工程师认为自己不善写作，索性就不写了。这实际是个偷懒的借口，写文档不需要华丽的辞藻、生动的语言，你只需要将问题讲清楚即可。

有时候工具不好用也会影响的文档写作。如果没有一个很好的写作工具将写文档嵌入到开发工作流程中的话，写作确实会增加工作的负担。

大多数人将写文档看做是工作的额外负担。我代码都没时间写，哪有时间写文档！，这其实是错误的观念，文档虽然前期有投入，但能让你代码的后期维护成本大幅降低，磨刀不误砍柴工这个道理相信大家都还是能理解的。

02

写文档的重要性

它有助于审视API。编写文档是确定API是否有意义的最可靠的方法之一。通常，编写文档本身会使工程师重新评估设计决策。如果你不能解释它，不能定义它，那你可能还没有设计好它。

它提供了维护的历史记录。在任何情况下，代码中的技巧都应该避免，但是当你盯着两年前编写的代码，试图找出错误所在时，好的注释将提供很大的帮助。

它使你的代码看起来更专业。开发人员自然会认为文档完备的API就是设计得更好的API。虽然情况并非总是如此，但它们通常是高度相关的。虽然这个好处听起来像是表面文章，但事实并非如此：一个产品是否有良好的文档通常是一个很好的指标。

这将减少其他用户提出的问题。对于编写文档的人来说，随着时间的推移这可能是最大的好处。如果你必须向某人解释某件事不止一次，那么记录该过程通常是有意义的。

03

像管理代码一样管理文档

有明确的责任人维护；

有统一的内部规范；

定期更新；

有变更和评审机制；

有问题反馈和更新机制；

明确文档的读者是谁

04

文档类型

作为工作的一部分，工程师会编写各种不同类型的文档：设计文档、代码注释、操作文档、项目页面等等。这些都可以算作文档。但重要的是要知道不同的类型，不要混合类型。一般来说，文档应该有一个单一的目的。正如API应该做一件事并且做好一样，避免在一个文档中做几件事。软件工程师经常需要编写几种主要类型的文档：

参考文档，包括注释

设计文档；

教程；

概念性文档；

2.设计文档

大多数公司在项目开始之前都需要有设计文档。软件工程师通常使用团队批准的特定设计文档模板来编写建议的设计文档。然后还需要在特定的团队会议上讨论或评论设计的细节。一个好的设计文档应该涵盖：

设计目标

实现策略

利弊权衡和具体决策

替代方案

各方案的优缺点

一份优秀的设计文件，一旦获得批准，不仅可以作为历史记录，还可以作为项目是否成功实现其目标的衡量标准。大多数团队会将他们的设计文档进行归档，以便在后续的时间查看。在产品发布前检查设计文档通常是很有用的，以确保编写设计文档时所陈述的目标在发布时仍然是所陈述的目标（如果不是，那么文件或产品都可以进行相应的调整）。

4.概念性文档有些代码需要更深入的解释或见解，而不是仅仅通过阅读参考文档就能得到的。在这些情况下，我们需要概念性文档来提供api或系统的概述。

概念性文档处理可能是API的库概述、描述服务器中数据生命周期的文档等。概念性文档是用来扩充而不是替换参考文档集的。有时候这和参考文档会有些内容重复，，但主要还是为了更深层次的说明某些问题、解释清楚某个概念。概念性文档没有必要涵盖所有边缘情况。在这种情况下，为了清晰度而牺牲一些准确性是可以接受的。概念性文件的要点在于传达理解。概念文档是最难编写的文档形式。因此，它们通常是软件工程师工具箱中最容易被忽视的文档类型。而且还有另外一个问题，没合适的地方放，参考文档可以写代码里，落地页可以写项目主页里，概念性文档似乎也只能在项目文档里找个不起眼的角落存放了。概念文档需要对广泛的受众有用：无论是专家还是新手。此外，它需要强调清晰性，所以它通常需要牺牲完整性（最好留作参考）和（有时）严格的准确性。这并不是说概念性文件应该故意不准确;这只是意味着它应该关注常见的用法，而将罕见的用法或副作用留作参考文档。

05

文档Review

在一个组织内，光靠个人去维护文档是不行的，必须得借助群体的智慧。在一个组织内部，文档的变更也应该像代码的变更一样，需要被其他人Review，以提前发现其中的问题并提升文档的质量。技术文档得益于三种不同类型的review，每种审查都强调不同的方面：

专业的视角来保证准确性：一般由团队里比较资深的人负责，他们关注的核心点是文档写的对不对，专不专业。如果Code Review做的好的话，文档的Review也属于Code Review的一部分。

读者视角保证简洁性：一般由不熟悉这个领域的人来Review，比如团队的新人，或者文档的使用者。这部分主要是关注文档是否容易被看懂。

06

文档写作的哲学

下面的部分更多地是关于技术写作最佳实践的论述。5W法则相信大家已经听的多了，分别是WHO， WHAT， WHEN， WHERE， WHY，这是一个广泛被用在各行各业的法则，写文档当然也不例外。WHO：正如前面所说，文档的针对对象是谁，读者是谁。

WHAT：明确文档写作的用途，通常仅需说明文档的用途和目的就能帮你搭建起整个文档的框架。

WHEN：明确文档的创建、Review和更新日期。因为文档也有时效性，明确相关日期可以避免阅读者踩坑。

WHERE：文档应该放在哪！建议一个组织或者团队有统一的永久文档存放地址，并且有版本控制。最好是方便查找、使用和分享。

WHY：为什么要写这篇文档， 你期望读者读完后从文档中获得什么！

1.三段式文档

所有文档，文档的所有部分都有开头、中间和结尾。尽管这听起来非常愚蠢，但大多数文件通常都应该有这三个部分。不要害怕在文档中添加章节;它们将流程分解为逻辑部分，并为读者提供文档所涵盖内容的路线图。

通常开头部分代表问题，中间部分介绍推荐的解决方案，结尾部分总结结论。但这也并不以为着文档应该有三个部分，如果文档内容比较多，可以将其做更细致的拆解，可以适当增加一些冗余的信息帮助读者理解文档内容。虽然很多工程师都讨厌冗余 极力追求简洁，但写文档和写代码不同，适当的冗余反而可以帮助读者理解。

2.好文档必备的属性

好的文档通常有三个方面：完整性、准确性和清晰度。很少在同一个文档中同时获得这三种信息;例如，当你试图使文档更完整时，清晰度就会开始受到影响。如果您试图记录API的每个可能的用例，您可能会得到一个难以理解的混乱。对于编程语言来说，在所有情况下都做到完全准确（并记录所有可能的副作用）也会影响清晰度。对于其他文件，试图明确一个复杂的主题可能会微妙地影响文件的准确性;例如，您可能决定忽略概念性文档中的一些罕见的副作用，因为文档的目的是让人们熟悉API的用法，而不是提供对所有预期行为的武断概述。

在每种情况下，一个好的文档都被定义为正在执行其预期工作的文档。因此，您很少希望文档执行一项以上的工作。对于每个文档（以及每个文档类型），确定其重点并适当调整编写，写概念性文档可能不需要涵盖API的每个部分，写一个参考可能想要这个完整，但可能必须牺牲一些清晰度等。所有这些加起来就是质量，不可否认的是，质量很难精确衡量。

07

结论

最后总结下本文几个关键点：

随着时间推移，团队的壮大，文档会越来越重要；

文档应该是开发人员工作流程的一部分；

每篇文档专注于一个目的；

文档是给读者看的，而不是你自己写作。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。