在日常工作之余，经常进行一些个人项目的开发。这些项目有时纯粹是为了娱乐，有时则是为了解决实际问题。虽然不是所有项目都能完成，但仍然喜欢记录下那些较大的项目。
当然，代码应该尽可能地自解释。但是，它能解释为什么选择了一种认证方案而不是另一种吗？它能快速总结所使用的技术栈吗？它能概述项目架构和托管基础设施吗？显然，答案是不能，也不应该。代码是相对较低层次的实现细节。但是，如果在6个月后（或更长时间）回到一个项目，或者向其他开发者、客户甚至投资者快速介绍主要点，将需要一些易于阅读的文档，最好还有所需的视觉图表。通常，这就是像Confluence这样的工具发挥作用的地方。
Confluence并没有太大的问题！它是一个文档和协作工具，在几个团队和组织中使用过，并且今天仍在使用。它非常适合有预算的团队和组织。然而，不建议将其用于个人项目，特别是那些可能几个月都不会接触的项目。这主要是因为Confluence（和Jira）会在120天不活跃后停用项目。不久之后，项目数据将被删除。完全理解Atlassian采取这种方法的原因。毕竟，这是免费层，所以他们并没有真正从托管文档（或工单）中赚钱，而且可能有很多死项目只是在消耗他们服务器上的存储空间，对他们来说这是无利可图的。但对来说，这有点破坏性。
当然，如果快速搜索Confluence的替代品，会发现很多选择。其中一些是付费服务（不想要），还有一些是免费的、需要自己托管的服务，需要安装软件、设置数据库和创建用户账户——这也是不想要的。最终迁移到的是Mkdocs，它实际上只是一个静态站点生成器（就像用来构建这个博客的Jekyll），专为项目文档设计。本质上，安装mkdocs命令行工具，搭建一个文档项目（它只包含一个yaml配置文件和一个文档页面目录），然后开始用markdown编写。如果文档只是针对开发者，实际上可以将其作为项目的一个额外顶级目录提交到项目中（或者如果喜欢的话，可以放在一个单独的仓库中），并允许未来的自己或同事开发者只需克隆项目并运行mkdocs serve就可以在需要时查看文档。虽然技术上，由于它是markdown，他们可能可以通过阅读markdown来应付——尽管认为渲染后的HTML文档比纯markdown更容易阅读。
让避免这个，好吗 :)
在mkdocs的安装页面上，他们提到可以使用包管理器（chocolatey、homebrew、yum等）进行简单安装，或者使用Python和pip进行手动安装。作为一个懒惰的Mac用户，最初选择使用homebrew进行安装，但后来在尝试安装自定义主题时遇到了麻烦，这个主题只能通过pip安装。为了避免这种情况，建议从一开始就使用Python和pip安装mkdocs。
实际上就是这样。一个本地安装的命令行工具和一些markdown，就有了美观、可导航、可搜索的文档，而且不需要任何托管。