当前位置：网站首页>【技术规范】：如何写好技术文档？

【技术规范】：如何写好技术文档？

2022-04-23 06:13:00 【格图洛书】

在大多数软件工程师对编写、使用和维护代码的抱怨中，一个常见的问题是缺乏高质量的文档。缺乏文档有什么副作用呢?当遇到一个bug时，这个缩写是什么意思?这份文件是最新的吗?在整个职业生涯中，每个软件工程师都抱怨过文档的质量、数量或者完全缺乏文档。

01

为什么需要写文档？

高质量文档对工程组织有巨大的好处。代码和api变得更容易理解。当他们的设计目标和团队目标被清楚地陈述时，项目团队会更加专注。当步骤被清晰地列出时，手动流程更容易遵循。如果过程被清楚地记录下来，那么让新成员进入团队或代码库所花费的精力就会少得多。

但是，由于文档的好处有一定的滞后性，通常不会给作者带来直接的好处。不像测试，编写完测试用例，跑一遍就有结果。毕竟，你可能只编写了一个文档，但之后它将被阅读数百次，甚至数千次；它的初始成本将摊销给所有未来的读者。文档不仅可以随着时间的推移而扩展，而且它对组织的其他部分的扩展也很关键。它有助于回答以下的问题：

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

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

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

虽然文档可以带来不少好处，为什么工程师通常认为它是糟糕的?其中一个原因，正如我们提到的，是好处不是立竿见影的，特别是对作者来说。另外还有以下几点：

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

  • 也有很多工程师认为自己不善写作，索性就不写了。这实际是个偷懒的借口，写文档不需要华丽的辞

版权声明
本文为[格图洛书]所创，转载请带上原文链接，感谢
https://getuluoshu.blog.csdn.net/article/details/121471877

边栏推荐

猜你喜欢

随机推荐