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