最新如何写好技术文档？，学习路线+知识点梳理

最新推荐文章于 2024-07-18 21:11:52 发布

2401_84919775

最新推荐文章于 2024-07-18 21:11:52 发布

阅读量575

点赞数 23

分类专栏：程序员文章标签： go 学习面试

本文链接：https://blog.csdn.net/2401_84919775/article/details/138798298

版权

程序员专栏收录该内容

57 篇文章 0 订阅

订阅专栏

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，涵盖了95%以上Go语言开发知识点，真正体系化！

由于文件比较多，这里只是将部分目录截图出来，全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频，并且后续会持续更新

如果你需要这些资料，可以戳这里获取

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

03像管理代码一样管理文档

软件工程师使用单一的、主要的编程语言来编写程序，他们仍然经常使用不同的语言来解决特定的问题。工程师可能会编写shell脚本或Python来运行命令行任务，或者他们可能会用c++编写大部分后端代码，但用Java编写一些中间件代码，等等。每种语言都是工具箱中的一种工具。

文档也应该如此:它是一种工具，用不同的语言编写，以完成特定的任务。编写文档与编写代码没有多大区别。与编程语言一样，它有规则、特定的语法和样式决定，通常是为了实现与代码中类似的目的:加强一致性、提高清晰度和避免理解错误。

文档通常与代码紧密耦合，因此应该尽可能地将其视为代码。也就是说，文档也应具有如下的属性：

有明确的责任人维护；
有统一的内部规范；
定期更新；
有变更和评审机制；
有问题反馈和更新机制；
明确文档的读者是谁

工程师在编写文档时犯的一个最重要的错误是只为自己编写文档。这样做是很自然的，并且为自己编写代码并非没有价值:毕竟，你可能需要在几年后查看这些代码，并试图弄清楚你曾经的想法。或者说在团队较小的时候，大家的工作交集很大，因此也能看懂你的文档，但是随着组织的发展，问题就逐渐凸显，新人会有这不同背景，团队大了以后，工作内容开始细化，交集减少，这时候之前写的文档对他们来说可能就很难理解了。

因此在开始写作之前，应该(正式或非正式地)确定文档需要满足的受众。设计文件可能需要说服决策者。教程可能需要为完全不熟悉代码库的人提供非常明确的说明。API可能需要为该API的任何用户(无论是专家还是新手)提供完整和准确的参考信息。

好的文档不需要修饰或完善。工程师在编写文档时所犯的一个错误是认为他们需要成为更好的作者。按照这个标准，很少有软件工程师会写。记住，我们的观众站在你曾经站过的地方，但没有你新的领域知识。所以你不需要成为一个伟大的作家;你只需要找一个像你一样熟悉这个领域的人。

04文档类型

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

软件工程师经常需要编写几种主要类型的文档：

参考文档，包括注释
设计文档；
教程；
概念性文档；

1.参考文档

参考文档是工程师最常编写的文档类型;事实上，他们经常需要每天写一些参考文档。代码注释是工程师必须维护的最常见的参考文档形式。这些注释可以分为两个基本阵营:API注释和实现注释。这两种用户之间的区别:API注释不需要讨论实现细节或设计决策，也不要假设用户和作者一样精通API。但是实现注释可以假定读者有更多的领域知识，但是要注意不要假设得太多。

2.设计文档

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

一个好的设计文档应该涵盖：

设计目标
实现策略
利弊权衡和具体决策
替代方案
各方案的优缺点

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

3.教程

每个软件工程师，当他们加入一个新的团队时，都会想要尽可能快地跟上进度。拥有一个引导人们完成新项目设置的教程是非常有价值的。

通常情况下，编写教程的最佳时机是你第一次加入一个团队的时候。拿个记事本或其他方法做笔记，写下一路上你需要做的所有事情，假设没有领域知识或特殊的设置限制;完成之后，可能会知道在这个过程中所犯的错误和原因，然后可以编辑你的步骤，以获得更精简的教程。重要的是，写下一路上你需要做的一切;尽量不要假定任何特定的设置、权限或领域知识。

这类型的文档写作中，要求写作者尽可能站在用户的视角上思考，极力避免出现和用户的认知偏差，力争每个步骤做到明确无歧义，每两个步骤之间做到紧密衔接。

4.概念性文档

有些代码需要更深入的解释或见解，而不是仅仅通过阅读参考文档就能得到的。在这些情况下，我们需要概念性文档来提供api或系统的概述。概念性文档处理可能是API的库概述、描述服务器中数据生命周期的文档等。概念性文档是用来扩充而不是替换参考文档集的。有时候这和参考文档会有些内容重复，，但主要还是为了更深层次的说明某些问题、解释清楚某个概念。概念性文档没有必要涵盖所有边缘情况。在这种情况下，为了清晰度而牺牲一些准确性是可以接受的。概念性文件的要点在于传达理解。

概念文档是最难编写的文档形式。因此，它们通常是软件工程师工具箱中最容易被忽视的文档类型。而且还有另外一个问题，没合适的地方放，参考文档可以写代码里，落地页可以写项目主页里，概念性文档似乎也只能在项目文档里找个不起眼的角落存放了。

概念文档需要对广泛的受众有用:无论是专家还是新手。此外，它需要强调清晰性，所以它通常需要牺牲完整性(最好留作参考)和(有时)严格的准确性。这并不是说概念性文件应该故意不准确;这只是意味着它应该关注常见的用法，而将罕见的用法或副作用留作参考文档。

05文档Review

在一个组织内，光靠个人去维护文档是不行的，必须得借助群体的智慧。在一个组织内部，文档的变更也应该像代码的变更一样，需要被其他人Review，以提前发现其中的问题并提升文档的质量。

技术文档得益于三种不同类型的review，每种审查都强调不同的方面：

专业的视角来保证准确性：一般由团队里比较资深的人负责，他们关注的核心点是文档写的对不对，专不专业。如果Code Review做的好的话，文档的Review也属于Code Review的一部分。
读者视角保证简洁性：一般由不熟悉这个领域的人来Review，比如团队的新人，或者文档的使用者。这部分主要是关注文档是否容易被看懂。
写作者视角保证一致性：由写作经验丰富或者相关领域比较资深的人承担，主要是为了保证文档前后是否一致，比如对同一个专业术语的使用和理解是否有歧义。