本文由 简悦SimpRead 转码，原文地址 levelup.gitconnected.com
运行文档说起来容易，做起来难。不仅有大量的地方可以托管文档......。
运行文档说起来容易做起来难。不仅有大量的地方可以托管文档，而且你得到的工具也有很大不同。
文档是很难的。不仅仅是因为为普通读者写作并不容易，而且还因为为你的（公共）文档找到正确的解决方案可能是一个真正的挑战。有很多方面需要注意。不仅仅是事物的外观，还有你所获得的功能，价格，维护，以及写作所需的努力。是的，在一个工具中编写完全相同的文档可能比在另一个工具中花费更多的时间。试着用markdown或富文本编辑器写同样的文本，哪种对你来说最有效？
一边是自我托管的解决方案，从Vuepress到Docsify，还有许多其他的。作为一家开源公司，使用自我托管的开源解决方案是很有意义的我们自己。然而，自我托管带来了额外的维护，你需要编写的自定义功能，你需要做的造型和/或设计，以及更多。考虑到我们只是一个小公司，我们不能花几个小时来维护，甚至建设一个几乎可以用低努力就能实现免维护的网站。
另一方面是托管平台，如Gitbook和Readme。这些平台很适合快速推出文档，为我们管理托管和更新，并且在管理方面无后顾之忧。
（Gitbook.com）
我们会不会喜欢使用我们自己的工具，Budibase？嗯，不尽然。Budibase并不是为托管文档而建的；Budibase在管理工具、表格和内部应用方面要强得多。你得知道你的优势和劣势!
因此，我们转向了托管解决方案。而在这个领域有几个参与者。我已经提到了其中的两个解决方案；Gitbook和Readme，我们将在这里讨论这两个解决方案。两者都有好处和坏处，但对我们来说有一个明显的赢家。
直到最近，Gitbook才是我们的首选工具。它是在Github上托管文档的一个很好的扩展；它在引擎盖下使用分支，允许协作，而且非常具有开源意识（尽管他们的工具不再是开源的）。甚至在Github上提交PR也能与Gitbook很好地配合。托管的Gitbook解决方案的设计也很简单，但对用户来说很清晰。不过，对我们来说，好处到此为止。Gitbook 的加载速度很慢，不仅在后台，对我们的用户来说也是如此。甚至点击Gitbook界面上的编辑按钮也很慢。它并没有立即打开编辑界面，而是在后台加载创建一个新的分支，然后才真正显示界面，这使得工作相对缓慢。当你试图编辑几个页面时，这类延迟最终会增加到轻微的烦扰。
另一个缺点是设计，这在很大程度上是一种看法。Gitbook的设计相当简单，没有什么启发性，而且在这方面也感觉略显过时。虽说过时并不重要，但总的来说，这种感觉并不是我们所追求的。而且，对于Readme和Gitbook来说，所有由它们托管的文档网站看起来都差不多，但在风格上却有很大的区别。可能是我们的品味不同，但对我们来说，在设置 Readme 时，我们一直在重复一件事；"伙计，Readme 看起来不错"。
不要误会我的意思，Gitbook仍然是一个优秀的解决方案，我仍然会推荐它。只是Gitbook并不适合我们。所以，在你对我的文章下定决心之前，一定要看看这两个软件 它们都有很好的免费层级，所以绝对没有理由不在承诺之前尝试它们。而且考虑到它们都是基于Markdown的，切换起来也应该很容易。
（Readme.com）
那么关于这个转换。我们最近决定转换。我们即将推出一个新的API，我们刚刚发布了它，而API文档是一件很棘手的事情。编写你自己的参考表、例子和指南，并提供一个清晰的概述，这不是你在一个实例中就能完成的。然后Readme突然出现，给了我们一个OpenAPI-2-文档的解决方案。我们有什么理由忽视这个奇妙的事实呢。我们本来要花很多时间来记录API，并考虑使用Postman作为托管我们API规范的解决方案。不过，最终我们还是更愿意把API规范整合到文档中。而Readme甚至可以通过整合和预填认证密钥来进一步提升。我们还没有到最后一个部分，但我们会的。
这很好地证明了为什么你需要为工作挑选合适的工具。如果我们坚持使用Gitbook，并在那里编写API文档，我们可能会花一周时间来做这件事，而且做得很糟糕。然而，迁移我们现有的所有文档只花了不到一周的时间，而且我们最终为我们的用户提供了一个更容易使用的解决方案。正如前面提到的，我们也可以在Postman上托管我们的API规范，但这样我们就有两个不同的地方可以让我们的用户找到信息，这可能会让人困惑。
所以，我们迁移了我们的文档，当一切顺利时，我们改变了我们的DNS设置。一小时后，新网站看到了它的第一个流量。我有点紧张，但一切都很简单。除了一些页面没有被迁移，或者有立即重写所有内容的冲动之外。
在把所有东西切换过来的几天后，唯一仍未完成的事情是谷歌的重新索引。当然，这是从托管平台转移到托管平台的缺点之一；你不能控制URI，而这对SEO来说很重要。幸运的是，最终的结果应该是更好，而不是更糟。所以必须做出必要的牺牲。如果你有能力自我托管文档，你可能已经能够保持所有的URLs不变。
发布之后
所以我们已经上线了，大约一个星期了，我们看到一些很好的流量正在冲击文档。数以千计的页面浏览量已经被记录下来，这给我们带来了一些很好的洞察力。
Readme的分析部分也比Gitbook更清晰和广泛。我们清楚地看到人们在哪里浏览，人们在我们的文档中寻找什么，以及不要低估页面底部的 "这个页面对你有帮助吗 "的大拇指。我们已经得到了很好的洞察力，人们在哪里没有找到他们要找的信息，我们需要写什么样的页面和指南来适应这种情况，以及如何继续。
另一个令人惊讶的补充是，用户可以对文档的改进提出建议。在这个页面上有一个很好的按钮，而且这个建议有一个简单的 "合并 "按钮。以前，如果用户想在Gitbook上这样做，你会在我们的文档库中找到，不得不再次找到相同的页面，并通过PR建议进行修改。自述程序则顺畅多了，给用户带来了更好的体验。
总结
所以是的，非常赞美Readme团队，他们建立了一个了不起的文档平台。我们现在非常高兴地使用它。虽然我们对Gitbook并不感到不满意，但这种过渡确实让我们感到安心。但归根结底，最重要的是为工作挑选合适的工具。如果你只是在记录一个工具，而且你不需要比静态markdown文件更多的功能，那么你会对Gitbook非常满意，或者是自我托管。
我们，在Budibase，现在可以把更多的时间放在我们应该做的事情上，制作一个伟大的、开源的、低代码的工具。而对我个人来说呢？我现在可以把我的时间集中在改进文档、推广和支持上，这是很有必要的。
我很好奇你的想法。你也会这样做吗？还是完全采取其他方式？让我知道!
