技术文档，they are my collection！

工作

今天这篇文章，献给一直撰写技术文档的自己。我自认为是公司中最爱写文档的人了，我们是一个不到40人的小公司，公司作风没有多么严谨，领导也不会要求我们写技术文档。但是从入职初至今，我一直保持着写技术文档的习惯，每当遇到中大型的需求，我是必须贯彻文档先行的，即使这篇技术文档只是写给自己的。

编写技术文档是一个理清软件开发思路的一个过程，我认为开发一个中大型的需求，需要事先做好软件设计工作，然后才能开始开发。我知道在很多大型公司，架构设计、软件设计、开发都是分角色的，每个人专注于干一件事情。但是小公司没有这么多人力，不分这么多岗位。但这不意味着我们就可以舍弃软件开发流程中的某一环节。软件工程是一个严谨的过程，开发是一个充满逻辑思考的过程，我更喜欢一步步来，遵循严谨的开发流程，事先梳理好开发逻辑，然后创造出更好的产品。

上图是我总结的多个技术文档的模板。they are my collection！

学习

除了工作，日常的学习过程中我也会编写一些总结性的技术文档。目前我在使用的工具是阿里的语雀，它可以使用很多的MarkDown 语法，很适合从事IT 行业的人员编写技术类的文档，我很推荐语雀这款APP。

使用语雀之前，我也尝试过很多写技术类文档的APP，如印象笔记，Notion，VsCode的Markdown 插件，还使用过各种画脑图的软件。最终，我认为我编写技术类文档的归宿是语雀。首先它的免费版基本可以满足我的一切日常所需，我不需要为其付费。而印象笔记我记得我使用的时候还开了一年会员，因为它有很多功能是会员专享的。而且个人感觉印象笔记对于Mark Down 语法的支持和展示效果并不如语雀。

第二点语雀原本就是阿里巴巴一直在使用的技术文档平台，所以它天生就是为了编写技术文档而存在的，与之对比的是Notion，Notion 是一个多样化的富文本工具，它更像是一个做总结，列计划类的工具，更趋向于以页面的方式让简单的东西生动化，在我看来是一个增加趣味性的工具。用了一段时间后，我觉得我还是更喜欢采用一个简单列表来做一个计划，或者使用Excel 列一个计划。而技术类文档也不需要花里胡哨的东西，所以我就把Notion 放弃了。

使用脑图是我看了一本关于脑图的书，然后觉得脑图更适合人类大脑的思考，就有一段时间一直使用脑图APP总结我的技术文档。但事实上技术类文档是不适合脑图的，脑图可以是技术类文档关于总结的一部分，作为其中的插图使用，但它绝不能完全代替技术类文档。

VsCode 的MarkDown 插件确实是一个好用的工具，在使用语雀前我有一年的时间使用VsCode 编写我的技术类文档。但是让我用语雀的原因是，语雀有一个一键分享功能，可以将自己的技术类文档以链接的方式直接发给别人看，而且别人还可以进行协作编辑，而这是VsCode所不具备的功能。语雀APP使用至今，让我觉得非常顺手，所以以后大概率也会一直使用语雀进行技术文档的编写了。

用了语雀不到一年时间，我编写了大概300多篇技术文档，大概60万字。they are my collection！

画图

技术类文档少不了的就是插图，一篇带有图例的文档会让人感觉更舒服，更具专业性。我的技术类文档使用的图例一般是UML 图，BPMN图，以及对于一些前端的设计我也会画简单的原型图。而这些图我现在都使用一个APP 搞定，就是ProcessOn。ProcessOn可以画各种图形，虽然它不像很多专业的软件如Axure RP那样具有细致入微的设计体验，但它胜在操作简单，图形丰富，简单来说就是够用。而像Axure RP这种软件我也用过一段时间，感觉出图速率不如ProcessOn，且功能复杂，需要时间学习，但是我很多时候只是画一个简单能表达意思的简易原型图而已。

简单展示一下ProcessOn 的页面,使用ProcessOn 至今，我画的图大概200多了吧，多用于技术类文档的示例图。they are my collection！

AICG

提到AICG想必做IT行业的人应该都不陌生,它是最近几年最火的概念，现在已经成为我在开发过程中，以及编写技术类文档的过程中比不可少的一个资讯，优化类APP。AICG 的平台有很多，从一开始火爆全球的ChatGPT，到现在中国市场百家争鸣的各种大模型平台，如智谱AI，豆包，通译千问，讯飞星火等。。。AICG 在不断进化，逐渐渗透到人类日常生活的方方面面。

在编写技术类文档时，我一般使用AICG 干两件事，一件事是查询自己不懂的技术，或淡忘的内容，结合百度，CSDN，starkoverflow等平台做快速总结学习，以方便后续技术类文档的使用。第二件事就是我会使用AICG 做整体的文字优化工作，让语言更通顺，文本更具有技术性。

结合我使用AICG 的感觉，我认为AICG 可以用，但不可信。因为很多情况下AICG 输出的内容是错误的。很多情况下它生成的内容看起来非常合理，但实际上它的逻辑并不是建立在事实的基础上的。所以对于AICG 的输出，我们要始终保持存疑的态度。我们需要做到广泛求学，不能忘记根本的学习路径，就是看书学知识，而不是一味的依赖于AICG。所以我认为AICG 的使用终将和人类是一个相辅相成的过程，它帮助你回答一些遗忘的东西，优化一些你想要的东西；你引导它指向正确的东西,帮助它修复一些错误的东西，这个过程应该是贯彻始终的。