最近重新梳理了一遍公司某开源产品文档，大致结论是用户体验是非常非常差: 结构错乱，没有章法，思维跳跃太大容易打破用户的惯性思维，总之头几次看文档就两个字：脑卡。
目标
完善文档内容
渐进式上手，提高使用体验：文档功能分层，难度和内容按照：新手入门/项目原型/项目落地/进一步优化 进行分层
加强企业版引流，产品是分为开源版与企业服务的，这次企业版的一些特性和方案文档里也介绍进去，但明确提示企业版才能用，有意无意让用户了解企业版，能促进对产品认知提升转化率
新增技术指南如部署、监控管理、设备管理等官方指南，降低用户集成难度；官方的最佳指导是非常重要的，虽然产品可以与很多东西集成，但是如果可以排除一些场景，官方应当明确给出最佳事件指南或者至少摆出利弊，模棱两可公关大法很头疼
调动社区活跃性，之前文档只是单纯介绍功能，用户之前没有任何交流。现在计划提供官方/社区用户教程资源外链、用户信息展示、项目集成示例等，借助社区增加产品曝光度，促进用户相互交流。
开源项目应该建立一个合理的渠道，给一部分用户收获成就感的机会，引导大部分用户去复制粘贴！
重点来了
写文档总要有目录的吧，文档质量很大一部分也取决于目录。来来回回和同事搞了半天我终于明白几个道理，一下以下都是辛酸和泪水：
目录顺序不是最重要的，但是目录下面内容要统一，内容按照目录归类
排除初次使用，用户大多数情况下不会按文档所给的顺序阅读，只会按照需求去查找文档，去反复的用
目录不要太多，建议不超过 10 个，也不能太少，初次见面能让用户“猜”到 “我想要的东西就在这里”，杜绝脑卡，最多两步达到查阅目的
总结来说，产品嘛，满足用户小小的自以为是，收获会心一笑：我真聪明，一找就找到。
满足不了的，记住一句话，让用户吃两次亏就学会了。
拓展阅读
关于开源文档系统，找了很多个产品也没有个比较好的产品，文档系统无非就几个：
- 好编写，易上手，Word 不错 Markdown 也足够用了，reStructuredText(rst) 用起来就很脑卡
- 容易组织目录，分清文档层次
- 适当的拓展性和私有化定制功能
- 导出 PDF，非常重要，发给客户或者其他地方阅读
- 适当的版本控制
- 响应速度要快，Gitbook 从安装插件到大规模编译的时候都很头疼
找了 Python 广泛用的sphinx，Nest.js 中文文档用的docsify，以及前端用的 VuePress 都没有很好的满足以上条件，语雀之类的在线产品有不在考虑范围。
最后决定还是继续用 Gitbook，有推荐不？