一点点进步的 OceanBase 数据库文档！

欢迎访问 OceanBase 官网获取更多信息：https://www.oceanbase.com/

自 2020 年 OceanBase 以独立子公司开始全面推进商业化以来，提供更好更易用的数据库文档一直是 OceanBase 努力的一个重要方向。

如何通过文档让用户更快速更便捷地了解和使用 OceanBase 数据库？如何辅助用户更快速地解决使用过程中遇到的问题？是 OceanBase 文档一直在探索和前行的方向。

过去的两年里，我们收到了很多数据库爱好者对 OceanBase 文档的反馈和“吐槽”，也走出去和很多数据库使用者和专家进行了很多交流。 文档有但是不能解决问题、文档有但是找不到、文档缺失等 是让用户头大的几大问题，给用户自助使用带来了掣肘。面向越来越多的数据库爱好者自助学习和使用数据库的大背景，带着用户的声音和期待，我们启动了 OceanBase 文档易用性演进。

在这期间，我们也一直在思考几个问题，文档如何能更符合用户的诉求能真正提供帮助、文档如何能更易用、文档如何能持续的演进和迭代。我们认为文档需要聆听用户真实的声音，需要越辩越明，需要集思广益，我们要做更 open 的文档。

我们最近做了什么？

近期，结合着 OceanBase 数据库 4.x 的新架构，OceanBase 针对文档做了很多讨论，结合之前大家反馈的一些文档建议和问题，对文档和文档中心做了一些调整，在文档内容上也更多地去贴近用户视角和场景。

▋ 解决文档「不好找」的问题，文档更聚焦，20% 的文档覆盖 80% 的问题

作为一款较复杂的软件，我们需要提供大量的文档来满足用户在不同场景下的信息获取诉求，这些文档包括操作指导、技术原理介绍、参数/视图/错误码等参考类信息。文档丰富可以确保用户想要的信息都有，但是随之带来的问题是如何更好的组织这些信息，才能让用户在这么多信息中比较快捷比较精准的找到自己需要的。

之前 OceanBase 文档将面向同一用户角色的各类信息（操作指导、技术原理、参考信息等）做汇聚来统一呈现，力求呈现更全的信息。 信息全，但是同时也带来了不小的信息“干扰”，信息查找困难， 这些庞杂的信息中，可能只有少量是大部分用户在日常工作中高频会查阅的信息，剩余的大量信息用户主要是以按需查找为主。

在这一次的调整中， 我们协同 OceanBase 数据库的资深 DBA 一起反复讨论和梳理出了用户使用 OceanBase 数据库的核心链路和场景，将这些核心链路和场景的相关文档按照用户旅程来单独呈现。 同时将用户按需检索类的文档作为参考信息单独呈现，对文档信息按照用户角色和内容类型做了分层处理，文档更轻量，定位更清晰。

▋ 解决文档「不好用」的问题，文档更加用户视角和场景化

以前用 OceanBase 文档的时候是不是会有点什么都写了，又好像没写什么的感觉。我们深入剖析了一下，主要是因为之前的文档没有和用户的“语言”同频。之前的文档比较偏向功能视角，在更多的去告诉大家我们有什么，但是用户日常的路径是我遇到了什么问题应该怎么去解决。

在这次的调整中，我们着重向用户视角和场景化的大方向上演进，文档更重要的去讲述我们能够解决什么问题。“是什么、为了什么/解决什么、什么时候/什么场景下使用、如何使用（提供详细的使用 demo 和说明）、注意什么、如何验证”，更贴近用户的使用思路和实际场景，务求能够真正提供帮助。

🌟以隔离节点为例

▷ 为什么需要隔离节点？

▷ 什么情况下需要隔离节点 ？

▷ 隔离节点的逻辑 ？

▷ 如何隔离节点？

▷ 详细的操作信息和适用场景

▷ 必要的风险提示和使用建议

内容好很重要，内容便于使用也很重要。 在优化文档内容的同时，我们也针对大家使用 OceanBase 文档过程中遇到的体验问题进行了小小的调优，以提升文档中心使用体验，进一步解决用户痛点问题。

▋ 解决文档「找不到」的问题，提供更多的文档使用引导

OceanBase 除了分布式数据库之外，还提供了丰富的生态工具产品来辅助用户更好更便捷地使用数据库，这些产品都有配套文档，但是之前文档中心没有提供明确的入口，这些文档对于用户来说可能是“不可见”的。

OceanBase 提供了很多内容，除了产品版本配套的使用文档之外，也会提供面向不同用户角色不同使用场景的教程和视频类内容，但是这些内容都隐藏在了 OceanBase 大量的文档中，对于用户来说可能也是“不可见”的。

针对这些“不可见”的问题，我们在文档中心提供了文档“大地图”，用户可以根据文档导览图快速看到都有哪些内容可用并快速直达。

▋ 解决文档「不好搜」的问题，搜索结果可筛选，搜索分层更精准

OceanBase 的文档很多，搜索范围的精准性对于快速找到想要的内容至关重要。

我们在之前的用户访谈中，反复听到用户对于快速准确查找到想要文档的痛点，“文档不是没有，但是不容易找到”、“搜索结果里，有很多同名文档，点进去才发现不是自己想看的版本”等等等等。

针对搜索结果“太多”的问题，我们提供了搜索结果筛选的能力，大家可以通过选择想要的产品和版本来缩小搜索结果的范围。

针对如何提升站内搜索精准度的问题，我们对搜索做了分层处理，现在您可以搜整个官网一览所有内容，也可以专注搜索文档，还可以更加精准的搜某个产品某个版本的文档，搜索范围可泛可精准，满足不同场景的诉求。

除了上述调整之外，我们还针对文档的导航目录、文档的样式等做了很多细小的调优，欢迎到 OceanBase 文档中心体验这些小而美的改进。

🌟更多小的体验提升

▷ 功能更易用

▷ 文档切换、PDF 下载、文档反馈等功能更明显，使用路径更清晰

▷ 更丰富的文档样式

▷ 设计了更多文档样式，让信息获取更便捷

与我们一起共建更易用的数据库文档

OceanBase 一直相信更好的数据库文档一定来源于热爱数据库的大家们的共同打磨和建设。后续我们将以文档提升活动、文档专家小组、主题性文档讨论等形式陆续发起 OceanBase 文档共建活动，和大家一起打磨更好用的数据库文档。

▋ 一起交流呀，文档越磨越易用

同步一个小活动，近期，OceanBase 4.0 文档和文档中心都进行了一些调整，我们诚邀大家一起来体验试用：

您可以给我们的文档提交 pr，反馈在使用过程中的各种问题；也可以在社区文档帖子下反馈建议，跟帖互动，碰撞交流。 我们将针对优质反馈赠送定制键盘、Polo 衫、定制无线充等精美礼品和社区积分喔～感兴趣的小伙伴可以点击链接（https://ask.oceanbase.com/t/topic/35602746）查看具体的活动细节。

▋ 文档专家小组，文档的智囊团

文档需要长期的建设和持续演进，我们也会把文档共建作为一个长期的计划来推进。为了更好的支撑文档共建的运作，构建更 open 的数据库文档，OceanBase 拟筹建文档专家小组。文档专家小组后续会深度参与到 OceanBase 文档的共建、文档策略讨论、和文档演进中来。

更多文档专家小组的建设和运作机制的细节信息，我们后续会在 OceanBase 官网和社区透出，期待您的关注和参与。

写在最后

我们赶上分布式数据库的大潮，也遇上了数据库学习和使用的热潮，构建更好的数据库文档，服务更多的数据库爱好者和使用者，让我们一起共建更易用的数据库文档，让文档发挥更大的价值。

最后，墙裂建议钉钉扫码加入我们的钉钉群（群号：41203246），本群为我们文档贡献社区官方交流群，OceanBase 文档同学将在群里实时互动答疑，同步活动积分和最终结果，并为您解决活动中遇到的各种问题~🎉

欢迎访问 OceanBase 官网获取更多信息：https://www.oceanbase.com/