概述
对于技术人员而言，时时刻刻逃不掉文档。我们需要看文档，写文档。
但，更多的时候，对于我而言，很多文档我却看不明白，或者说没有办法快速的阅读一篇文档。
同时，我也写不出来，让人一看到啧啧称赞的文章。
不禁在想，这样的我，能够产出什么，写出来的代码没有人会用，没有人知道怎么实现的。同时，也说不出来自己的东西哪里好，哪里用的什么技巧。怎么使用我写的东西，帮助别人构建更强大的代码。
提出问题
首先，提出问题，是什么原因导致的。知识不够，能力不够，还是自己懒。
- 首先排除自己懒，因为自己懒不懒只有自己知道，努力克服就可以了。
- 知识不够，需要多少知识才能写出来足够完整的知识文档，需要多少知识才能让自己整理出来足够完善的知识文档。
- 能力不够，写出来文档，但是没有具体的例子，没有能够支撑自己文档的足够例子。
- 不知道怎么写技术文档。
解决问题
- 了解一篇合格的技术文档
尝试去了解一篇大家称赞的文档是什么样子的结构，他们这样写的优势在哪里。我们这里直接去微软 Document 中找一篇文档，来一看究竟。
这里为了各种开发者的普适性，我使用了微软的 C++ 文档来作为参考文档。
https://docs.microsoft.com/zh-cn/cpp/cpp/?view=vs-2019
-
首先看目录
image.png
大致结构我们知道了，“题目 -> 正文 -> 参考文档” 总分总好评。
-
打开正文
image.png
图中的信息量比较大，我这里给大家总结一下，我这里是截取的屏幕，大家可以直接打开上面的连接，进行自行访问。
来到页面的中间，上面是正文的概述，下面是整篇文章的概述，对每个章节，标题为连接，下面是章节的内容介绍。
同样的，我们也可以在了解知识的情况下，对知识进行整合，格式如下：
正文：
<这里是简介>
概述：
<这里是全文的概述>
章节1：
<每章节的详细内容>
这里可以补充更多的章节
.......
总结：
<总结的内容>
引用：
<引用的内容>
-
重点
image.png
微软的文档，每一个小章节都控制到了1页纸上，这样细的力度让阅读者不会感觉到累，但这样的也需要文档管理软件支持。但是我们可以使用留白来解决，比如多个大标题之间可以留4个空白行。
这里微软的文档每段之间的段间距是加大的了，这样读者看起来的时候就不会因为拥挤的元素而辨别不出来重要的信息。
书写
当我们去写一篇文档的时候，发现虽然写了很好的文档，但是全都是文字的话，不能很好的表示我们想要表达的想法。比如在一些表示比较抽象的东西的时候，例如单单说 FSM 的实现很难让人了解到是怎么个情况。并且给出 FSM 的类图也是让人头大的。（图片引用自：https://juejin.im/post/6844904023670128647
）
类图
但是给出了这样的图，状态机就一目了然了，显然这样的会更容易让人理解
状态图
所以，往往我们想要写好一篇文章，工具的熟练使用是避免不了的，对于 UML 这种用在两个世纪的好东西，怎么能放过。
工具
PlantUML
这里给出 PlantUML 的官网：https://plantuml.com/
PlantUML是一个不得不讲的东西，好多大公司都在用的东西，我们熟悉的 Docker 、Kubernetes 、AWS等云厂商都在用的画图好工具，不仅可以画 UML，还可以画一些拓展的图，这里给出地址，大家自行瞻仰。
https://crashedmind.github.io/PlantUMLHitchhikersGuide/
同时PlantUML也可以和我们的VSCode集成，这里不再讲解，不了解的可以自行百度。
ScreenToGif
直接在微软商店里搜索 ScreenToGif 即可获取到这个软件，目前还是处于免费的状态，大家可以自行下载。
这个软件最大的用途就可以可以让你的配图动起来，这个就不需要我解释了，好用的一批，也能提升你文档的品质。
这里给出了一个我录的 gif 图供大家参考效果
ScreenToGif
尾巴
看到这里，不知道大家有没有注意到，这里我每一段之间，包括文字和标题之间都增加了一个空行来让我们的文字不那么拥挤，也并没有让每一段都相隔4个行，这样已经让文章达到了比较简洁的要求。
其实我注意到有一点，有些博主喜欢用文字中夹杂着超链接的形式来进行书写，包括对一些自己进行类似于
aaa 、 百度
这样的使用，对于我来说，感觉就像是洁白无暇的脸上长上了青春痘，脓包一样。这样的红点，你不得不去注意它的存在，这样的链接，你不得不想青春痘一样去点它。我其实只想读一读这篇文章，你想给出链接的话，直接在下方给出就行了，如果链接失效，我一眼就能看到它的顶级域名。当然这只是我个人的感觉。
总结
如何写好一篇文档，上面的都是没有意义的，重要的还是脑子里有东西。如果没有对整体的概念，又怎么能写出来总分总的结构。文档的意义在于，他们是不断成长的，每次的补充，每次的修改都将会让你的文档更上一个台阶。如此说来，如同软件的更迭一样，经过无数次修改迭代的软件，写出来的肯定是比较好的（前提是软件工程师每次修改都会让软件更加好）。
网友评论