Go最新搞技术，如何写好技术文档？_技术实现文档怎么写，2024年最新Golang框架体系架构的知识

最新推荐文章于 2024-10-11 07:55:40 发布

2401_84931491

最新推荐文章于 2024-10-11 07:55:40 发布

阅读量441

点赞数 3

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

本文链接：https://blog.csdn.net/2401_84931491/article/details/138769696

版权

程序员专栏收录该内容

57 篇文章 1 订阅

订阅专栏

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

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

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

既然理解了好文档的重要性，我们如何保证在时间的长河中维护好一份文档，这里有些相关的方法论，大家可以参考下。

1、像管理代码一样管理文档

对于如何写出好代码，整个技术圈已经有好多经验的总结了，比如书籍《重构》《代码简洁之道》…… 针对各种编程语言，也有相关的规范，比如国外的Google C++规范，国内的阿里Java开发规范等…… 但对于文档似乎相关的资料却很少。

但实际上，不应该把文档和代码割裂开来，你可以简单粗暴地认为文档其实就是用一种特殊语言书写的代码，这种语言就是人类的语言。这么想的话，实际上我们很多在代码和工程中总结出来的经验，也可以直接用在文档中。

比如：

a. 有统一的规范
b. 有版本控制
c. 有明确的责任人维护
d. 有变更Review机制
e. 有问题的反馈和更新机制
f. 定期更新
g. 有衡量的指标（比如准确性，时效性）

2、明确你的读者是谁

写文档有一个很常见的错误，那就是很多人文档都是写给自己看的，这种情况下就会导致你的文档只有自己或者和你有相似知识背景的人才能看懂，团队较小时这种问题还好，你们都做着类似的工作，所以也都能看懂文档。

但当团队逐渐壮大后，问题就会凸显出来，新人有时候有着和你不同的工作背景，甚至现在都做着不同的工作内容，这时候你之前写的文档他们就很难读懂了。

所以在写文档之前请明确你文档可能的读者会是哪些人，然后针对他们的特点着重关注如何才能让他们理解。

当然，文档也不一定要非常严肃和完美，只要能向你潜在的读者说明问题即可。记住文档是写给别人看的，不是给自己看的。

根据专业水平可以大致将读者分为三种新手、老手和专家，针对不同水平的人写作需要有侧重点。

比如针对新手，你需要重点介绍下里面涉及到的术语和概念，然后详细讲解具体的的实现。相反，针对专家你可以省去这些额外的信息。

注意，这里没有严格的标准，因为有些文章新手会看，专家也会看，这里还是需要具体情况具体分析。

另外一种对读者分类的方式就是根据读者阅读文档的目的来分类，比如有人知道自己遇到了什么问题，就是来找解决方案的。还有一批人只有一个简单的想法，但不知道具体的问题。

举个例子，以读数据库慢为例，前者已经知道数据库慢可能是因为数据量巨大且没有加索引，解决方案很简单加索引，这时候他可能需要知道的是如何正确地加索引。

而后者可能着重关注的是为什么读数据库会慢，这时候你可能需要额外重点介绍下数据库相关的原理。

3、清晰的分类

文档大致可以分为以下几种类型，每种类型也有自己不同的特点和写作侧重点。

（1）参考文档

参考文档也是大部分开发人员日常会使用和书写的文档，比如我们使用某个框架或者工具，都会有API说明文档，这就属于参考类文档。它并没有太多的要求，只要能向读者展示清楚如何使用即可，但无需向读者讲明具体的实现。

注：参考文档并不仅限于API文档，还包括文件注释、类注释、方法注释，要求都是能准确说明其用法。

（2）设计文档

很多公司或者团队在项目开始前都要求有设计文档，设计是项目实施的第一步，所以在设计文档书写的过程中要求尽可能考虑周全，例如该项目的存储、交互、隐私……

好的设计文档应该包含以下几个部分：

a. 设计目标
b. 实现的策略
c. 各种利弊权衡和具体决策
d. 替代方案
e. 各种方案的优缺点

写设计文档的过程也是你对整个项目做规划、思考可能出现问题的过程，设计的越详细、思考的越多，未来遇到问题的可能性就会越小。

（3）引导类文档

引导类文档也很常见，一般都是Step by Step的形式。比如我们在使用某个框架或者工具的时候，一般都会有个引导类的文档一步一步帮助你快速上手。大家写引导类文章大家非常容易犯的一个错误就是预设了很多背景知识。

一般使用文档都是有开发者写的，他们都非常了解这个工具的相关的知识，所以习惯性的会认为，啊这个知识点很简单用户也肯定会吧，实际上用户不一定会。这本质上就是一种认知偏差，这种现象在跨团队协作，尤其是多端协作的时候也非常明显。

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

（4）概念性文档

当参考文档无法解释清楚某些东西的时候，就需要概念性文档了。比如某个API的具体实现原理，其主要是为了扩充参考文档，而不是替代参考文档。有时候这和参考文档会有些内容重复，但主要还是为了更深层次的说明某些问题、解释清楚某个概念。

概念性文档也是所有文档中写作最难的，也是被阅读最少的，所以很多情况下工程师最容易忽视。而且还有另外一个问题，没合适的地方放，参考文档可以写代码里，落地页可以写项目主页里，概念性文档似乎也只能在项目文档里找个不起眼的角落存放了。

这类文档的受众会比较广，专家和新手都会去看。另外，它需要强调概念清晰明了，因此可能会牺牲完整性(可以由参考文档补齐)，也有可能会牺牲准确性，这不是说一定要牺牲准确性，只是应当分清主次，不重要的就没必要说了。

（5）Landing pages(落地页)

Landing pages就先简单翻译成落地页了，没想到啥恰当的翻译词。比如一个团队或者项目的导航页，虽然没啥具体的内容，但应该包含其他页面的链接。比如你新入职一个团队，比较成熟的团队都会扔给你一个文档，这个文档里包含常用的工具、文档链接，这就是这个团队的落地页。

落地页的问题就是随着时间的推移，页面可能会变得越来越乱，而且有些内容会失效，不过这些问题都好解决，做好定期的维护和整理就行。

落地页的技术难度不高，但要求内容的有效性、完整性和分类清晰。

4、文档Review

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

如何Review文档：

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

写文档的哲学

上面部分站在组织和团队的视角来看如何提高文档质量，我们接下来看看站在个人写作者的视角上如何写出高质量的文档。

1、5W法则

5W法则相信大家已经听的多了，分别是Who What When Where Why，这是一个广泛被用在各行各业的法则，写文档当然也能用（5W法则堪称万金油，啥地方都能用）。

**WHO：**前面已经说过了，文档是写给谁看的，读者是谁。
**WHAT：**明确这篇文档的用途，有时候，仅仅说明文档的用途和目的就能帮你搭建起整个文档的框架。
**WHEN：**明确文档的创建、Review和更新日期。因为文档也有时效性，明确相关日期可以避免阅读者踩坑。
**WHERE：**文档应该放在哪！建议一个组织或者团队有统一的永久文档存放地址，并且有版本控制。最好是方便查找、使用和分享。
**WHY：**为什么要写这篇文档，你期望读者读完后从文档中获得什么！

2、三段式写作

写文章一般都会有三个部分，专业写作者也讲究凤头、猪肚、豹尾，这三个词概括出了好文章三部分应有的特点。技术文档也算是文章的一种，所以一般也都会有这三部分，每个部分有其自己的作用，比如第一部分阐述问题，中间部分介绍具体的解决方案，第三部分总结要点。但这也并不意味着文档应该有三个部分，如果文档内容比较多，可以将其做更细致的拆解，可以适当增加一些冗余的信息帮助读者理解文档内容。

虽然很多工程师都讨厌冗余，极力追求简洁，但写文档和写代码不同，适当的冗余反而可以帮助读者理解，很简单，举个例子，比如写作中经常举例子，举的例子本质上就是冗余信息，生动的例子肯定是能帮助读者理解抽象内容的（我想这就是自举吧）。