文｜杨洋（花名：凯申 )
铜锁开源密码库创始人蚂蚁集团高级技术专家
本文 1284 字 阅读 5 分钟
1 前言
如大家所见，针对铜锁开源密码库（ *https://github.com/Tongsuo-Project*）的文档，我们正在逐步地进行一些改革。
其中，最大的一个变化是：我们把原来放在 readthedocs.org（简记 rtfd.io）上的教程和说明文档转移到了语雀上。
为此有必要和大家解释一下，这其中的原因以及背后的一些想法。
2 说说历史原因
铜锁开源项目自诞生以来，其文档管理不是那么的严格和统一。
铜锁派生自 OpenSSL ，而 OpenSSL 的文档则是以 perldoc 体系为核心，且混合了一部分的纯文本和 markdown 。OpenSSL 的这些文档内容均散落在 OpenSSL 源代码仓库的各个目录中。
对于 perldoc 所支持的 pod 格式的文件，可以被编译成多种不同最终格式的文档，这其中以 man 手册和 html 文件为主。
综上所述，所以铜锁项目在早期延续了编写 pod 文件并编译成 html 和 man 手册的这种模式，随着项目的发展，我们发现此模式存在若干不足，例如：
perldoc 这套体系过于古老，文档的编写依旧停留在“非可视化”的状态。且编译过程较为复杂，和 markdown 等相比不具备优势，也不够通用；
man 手册也比较古老，是单机的本地模式。查询文档的功能较弱，效率较低，不如 readthedocs 这种可视化的查询文档的方式来得便捷；
OpenSSL 的文档组织形式更多的是以 API 为出发点，而不是以“教程”为出发点，这对于很多新手用户来说无从下手。
3 早前的一些改进
为了解决这些不足之处，铜锁项目将文档的重心从 API 视角切换到了教程视角，即以教会用户如何通过使用铜锁来完成某种功能为核心目标，重新组织了文档的形态，并以 markdown 写了若干教程类的文档。
这些文档需要一个呈现平台，因此我们选择了成熟的 readthdocs.org 作为铜锁文档的发布地（https://tongsuo.rtfd.io ），并持续运行了一段时间。
在这之后，我们又发现了一些问题：
1.访问不便。readthedocs.org 是海外的文档托管网站，国内会出现访问比较慢甚至无法访问的状况；
2.不容易交互。更多的是单方面的信息展示，用户真有问题还是要到 Github 上提交 issue，效率比较低。
4 “文档社区化”的诞生
前段时间，我机缘巧合的参与了一档播客节目的录制
*（https://www.ximalaya.com/zhubo/343307074）*。
在录制过程中，大家也讨论到：是否可以将互动引入到开源社区的文档体系中，将开源项目的文档“社区化”，进而形成除了代码托管平台之外的、更加贴近最终用户的社区交流讨论形式。
受此启发，我们最后决定尝试将铜锁的全部文档迁移到语雀上，利用语雀的社区化能力，增强铜锁和其用户间的互动。具体来说有如下几点：
1.新的文档网站地址为：*https://yuque.com/tsdoc* 。目前有两个知识库，铜锁的各种文档均分类到这些知识库中，而且都是对全网公开的，后续我们也会根据需要对知识库去做一些调整；
2.用户可以在这些文档中进行评论；3.上述知识库的文档会每天同步备份到 Github 的指定仓库中；
4.现有的 *https://tongsuo.rtfd.io* 将不再更新。
此外，对于 API ，我们也会重新进行梳理，将铜锁特有的 API 整理后供用户检索查询。希望大家能和我们一起参与这场“文档社区化”的试验，欢迎伙伴们充分发表自己的意见、建议以及想法，一起将这次试验更好地落地。
本周推荐阅读