文档撰写的思考

源起

我在十几年前，在一家小公司做运维的时候，就曾经尝试过不同的CMS，想要作为个人以及部门的知识管理平台。那个时期，iPhone 1st尚未发布，软件行业还没有现在这么流行的各种静态网站工具，很多CMS(内容管理系统)是基于PHP开发（Wordpress, Joomla, Drupal)或者基于Python的 Plone 。那时候，我就一直在尝试不同的CMS/Wiki系统，而且每当看到精美的CMS网站(或者文档)，就想要了解是基于哪个平台实现的，自己是不是能构建出同样简洁美观的知识库。

如何借鉴CMS网站

既然说到CMS借鉴，如何分辨和找到某个心仪网站的CMS本源？

如果网站确实使用了某个CMS系统，那么 What CMS 提供了非常简单的检查方法: 输入网址就能够侦测该网站使用了哪个CMS平台。不过，如果网站是静态生成，例如 Sphinx文档 ，那么这个标准的CMS检测工具就无能为力。

备注

参考 How to Tell What Website Builder Was Used

倾向

我比较中意的网站风格是:

我最初以为是OpenStack自己开发的文档系统，但是在页面上没有找到文档平台线索。偶尔也能在其他平台看到类似风格，所以基本肯定是一个通用平台。

后来，我找到一个规律，很多开源软件在GitHub的项目中往往会提供doc目录存储文档，其中就会提供文档如何撰写或者使用什么平台撰写。在openstack项目中也能找到: OpenStack doc requirements 可以看到文档是使用 Sphinx文档

备注

我尝试了 Sphinx使用OpenStackDosTheme风格 ，发现还是需要做定制以移除默认嵌入的OpenStack网站的引用，所以并不是开箱即用。目前我暂时放弃，后续再看是否值得花费精力去定制修改。

备注

好的文档规范能够增强协作， OpenStack 组织撰写了详细的 OpenStack Documentation Contributor Guide ，提供详细的文档撰写实践指南。非常值得在构建大型项目时参考。

同样 OpenShift Documentation guidelines 提供了良好建议。不过，需要注意的是，虽然OpenShift文档风格非常类似OpenStack，但是OpenShift文档是采用 asiidoc 完成的。所谓 asiidoc 采用了独特的MARK_UP方式撰写，语法结构不同于 MarkDown 但是采用了一种变体文档格式，可能有比较大的学习成本。我并没有实践。

备注

Red Hat官方文档风格也非常类似，但是不是采用 Sphinx文档 ，而是类似WordPress的较为小众的 Drupal

我的实践

正如我在撰写 云图 – 云计算图志 ，文档是我梳理知识和想法最好的方式。我采用以下方式撰写文档:

  • Sphinx Doc

  • MkDocs

  • GitBook

  • Hugo

GitBook是我最早撰写 云图 – 云计算图志 的 Cloud Atlas 草稿 时使用的文档撰写平台。但我感觉GitBook采用Node.js来生成html，效率比较低，对于大量文档生成非常 缓慢。所以我仅更新源文件，很少再build生成最终的html文件。

Sphinx Doc是我撰写 云图 – 云计算图志 的文档平台，我是模仿Kernel Doc的结构来撰写文档的，现在已经使用比较得心应手，感觉作为撰写书籍，使用Sphinx Doc是比较好的选择。

不过，Sphinx采用的reStructureText格式比较复杂(功能强大)，日常做快速笔记不如MarkDown格式。我发现MkDocs比较符合我的需求：

  • 美观

  • MarkDown语法

  • 文档生成快速

此外，在很多Go语言开发项目中采用了 Hugo 作为文档系统，同样采用MarkDown格式的静态网站，定制性更强(也更复杂)，提供了大量的theme实现，甚至可以生成类似WordPress的个人网站。

我目前结合Sphinx 和 MkDoc 来完成日常工作学习的笔记

  • Sphinx用于撰写集结成册的技术手册

  • MkDoc用于日常工作笔记，记录各种资料信息采集

备注

Sphinx Doc 和 MkDocs 都采用Python编写，可以共用Python virtualenv环境，这也是我比较喜欢这两个文档撰写工具的原因。

我的构想

根据 Jamstack: Site Generators 统计，按照GitHub的Star数量排序， Next.js 是最受欢迎的静态网站生成器，其次是 Hugo文档

我准备采用 Hugo 来制作个人Blog Next.js 来构建个人网站

备注

Jamstack 是网页托管领域独角兽 Netlify 的旗下产品。由于专注于CMS和Site，其网站提供了相关信息参考。