微言码道 · 手记
写代码的这群人不写文档，为什么（下篇）
—— 继续接上篇，本篇介绍一些有利于程序员编写文档的常用工具
上篇文章，笔者试图分析为什么很多程序员不写文档。
本周，笔者基于自己过往的经验，推荐了一些能帮助程序员写出更专业的文档的工具。
当然，大家要明白，能不能写出专业的文档，工具仍在其次，你愿意主动写文档的意愿比任何工具更重要。
笔者就介绍一些工具，能帮助程序员写出好的文档的工具。
- 文档格式：Markdown
- 系列文档： GitBook
- UML等图形：Draw.io
- Api文档: OAS3.0
Markdown
很多程序员为文档格式而苦恼。
你不用担心，你的苦恼也就是大家的苦恼，为了减轻程序员写文档时对格式的苦恼，我们行业中的优秀的人员发明与设计了Markdown这种风格的文档格式。
Markdown是一种轻量级标记语言，创始人为约翰·格鲁伯。它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。[4]这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。
忘记Word这种玩意吧，也忘记怎么在Word中调整各种文档格式吧。程序员压根不需要去使用Word。
程序员只需要知道Markdown就足够了，事实上，笔者几乎所有的文档几乎全是基于Markdown的。
GitBook
Markdown是用来编写单个文档的，很多时候我们需要编写一系列的文档并放在一起，比如团队的编码规范等。
这个时候，你也需要GitBook了。 事实上，GitBook的文档就是基于markdown的，按照一定的规范与格式，编写一系列的markdown并把它们放在一起，形成一个在线电子书样的格式，这就是GitBook
如上图，笔者在团队中的编码规范，都是以GitBook来做的。
上图为笔者在2020年在做一个基于Electron桌面软件开发时的整体编码规范。
Draw.io
程序员很多时候都需要使用UML图或流程图，时序图等来对系统做说明。这个时候，你可能需要Draw.io这个工具就可以了。
它是一个免费开源的图形绘制工具，可以说是专为程序员而生的。它支持主流的比如UML图，流程图，时序图等，你可以用它方便的绘制各种设计图
笔者喜欢用这个工具来做领域建模。通常在编码前，通过它的UML图设计出核心领域模型及关系，这有利于笔者梳理对业务的理解
OAS3.0
这个可能适合于API文档，很多人可能知道Swagger，那OAS就是后面支持Swagger的规范。
它是一种规范，你可以用yml或json格式编写自己的API，然后再选用合适的UI来展现它。
很多人也是用的Swagger UI，但笔者觉得它太丑了，于是另外选择了一个开源的实现：Redocly
如上，笔者在今年的一个项目中，使用了OAS这种格式来编写API文档。
用它可以方便的生成很专业的API文档，这非常有利于你向别的团队或使用者来说明你的API。
四）
如果我们认真再审查下笔者上面工具，就会发现，很多文档的规范也好，方便的工具也好，都是国外的程序员制定或实现的。
事实上，这也是我们与国外程序员整体上存在的差距所在，我认为国外的程序员对方法论，规范，抽象这些东西更注重，而国内的程序员还是更偏重编码及项目成品。
今天的时代已经是科技的时代，未来的世界，只会需要越来越多的优秀的程序员，这是我们的机会与挑战，我们应该有努力让自己成为更专业的程序员的信念。
那我还是建议你去阅读程序员的职业素养这本书，再加上笔者本文所建议的：编写必要的专业性的文档
以此与各位同仁共勉！！