Selectel提供的每项服务都可以在您的个人帐户控制面板中进行管理。我们的许多产品也可以通过API请求进行控制。产品说明和API文档可在单个帮助中心中找到。
帮助中心的主要思想是为我们的客户提供机会，在他们方便的任何时候独立地找到他们有关Selectel服务的大多数问题的答案。
接下来，我们将讨论如何更改准备文档的方法并更新知识库的外观。
三年前，知识库及其视觉组件的技术实现完全满足了参考书中所有信息的需求。但是在过去的时间里，公司并没有停滞不前，而是一直在积极发展，既推出新服务又开发现有服务。
大约一年前，我们注意到现有的在线帮助不符合客户的要求：
- 导航菜单像一棵果树一样长大，不知道园丁在乎什么；
- 搜索不再方便。
- 视觉设计逐渐过时。
以前，我们产品的API文档无法公开获得-有些发布在my.selectel.ru控制面板中，有些是根据要求发布的，有些完全以文本格式描述的，并保持最新非常有问题。现在，在“ API文档”选项卡上了解了IT基础架构自动化以及与Selectel服务的后端交互的知识。
过去的一次小旅行
十到十五年前，在俄罗斯生产软件的公司很少能吹嘘获得在线帮助。操作手册以不断变化的风格以Word格式编写，试图将20世纪70年代创建的GOST应用于现代且不断变化的要求。
该模因在技术作家中仍然很流行：
时至今日，有些公司已经可以拥有便捷的站点界面，但是它们的文档仍然处于“ 45张pdf格式的下载说明”的水平。
在大型公司中，知识库与技术支持紧密相关。在理想的球形环境中，用户应该能够独立找到他们问题的80％答案，而无需联系技术支持。
具有文档的门户网站不会带来任何明显的收益，但是由于脚本的原因，它可以节省技术支持时间：
- 用户订购了服务。
- 设置时面临着显而易见的时刻。
- 我想联系技术支持。
- 我去了知识库，找到了我需要的信息。
- 没有联系技术支持。
- 利润！）
人们通常认为，帮助信息仅在用户连接后帮助用户理解服务。在出版了有关Windows工作信息的印刷书籍的时代，可能就是这种情况。但是现在，向潜在用户公开展示服务在购买前的运行方式变得同等重要。
大多数软件公司有时会为内部使用和客户开发API。公司通过发布公共API共享一组输入，以使客户能够将其服务与公司产品集成。
许多自定义任务可以自动化，包括使用现成的代码块作为构造函数来创建最人性化的基础架构。但是没有解释它是什么，它做什么以及如何使用的代码片段几乎没有用处-您不会费力地找出什么方法以及它们期望输入什么数据。
-需要做些什么来使公共API易于使用？作为API的文档，它们通常提供一个最小的交互示例，其中描述了方法（也称为端点）并提供了服务的响应。例如，使用Kubernetes API，您可以在Managed Kubernetes中自动使用集群和节点。
-附上文件！
我们面前有哪些任务
我们的视觉解决方案停止了使我们轻松找到所需文章的工作，并且现有菜单变成了不可读的“表格”。不可读的文档和无关的文字一样糟糕。人们习惯于阅读精心设计的材料。博客，社交网络，媒体-所有内容不仅呈现精美，而且易于阅读，令人赏心悦目。当前，对UX和UI的要求不容忽视，尤其是对于大量文本而言。
随着网站视觉设计技术的发展，我们注意到知识库的外观已过时。仅在知识库文章中使用锚和列表没有帮助。有必要修改文档和搜索引擎的整个结构。
文档常见问题
通常不存在或没有人知道它的存在
，无法找到的指令比不存在的指令好。
我们通过以下方式解决了这个问题-我们开始在月度邮件列表中添加指向有用文章的链接，在网站的产品页面上添加过渡，并通过公司通讯工具中的特殊渠道为公司所有感兴趣的员工设置通知。
过时且未及时更新
文档开发过程未内置在产品开发中，文档是在剩余基础上完成的。
在我们的案例中，产品经理还负责在使用新功能时记录该新功能。
文档非常复杂且组织不善，更容易向技术支持人员咨询如何解决问题
，为文档而编写文档是没有意义的，应该易于访问。查找文档的选项越多越好。
我们完全修改了知识库各部分的设计，在某些情况下通用模板不起作用，因此我们必须与所有利益相关者（产品经理，技术支持或前端开发团队）进行积极互动。
将API文档移至公共空间
使用在OpenAPI，Swagger或其他生成工具中生成的API文档的问题之一是与网站其余部分的复杂集成。用户必须能够轻松访问所有说明和文章-如果端点显示在一个视图中，而同一过程的文本描述显示在另一页上，则不方便。
保持单个视觉图像
创建单个帮助中心时，我们需要使用一堆“ git + markdown + swagger”来保持指令和规范的一致显示。
现在如何运作
技术实施
知识库最初是基于Confluence和静态页面生成器的组合构建的。
我们抛弃了Confluence，转到了“将文档作为代码”。现在，知识库的所有源代码都以Markdown格式排版，并存储在Git版本存储系统中。使用Hugo静态站点生成器从知识库中构建知识库站点。
该站点是从Git存储库的master分支中包含的文件生成的。只能通过请求请求来更新数据，这允许您在公共领域发布文档之前检查文档的所有新部分。这样的系统还简化了进行编辑的方法-公司员工可以始终创建分支并将所有必要的更改添加到该分支。
有关文档作为代码的更多信息
“将文档作为代码”的原理意味着使用与创建代码相同的工具来编写文档：
- 文字标记语言；
- 版本控制系统；
- 代码审查。
这种方法的主要目标是为整个团队在最终结果上的联合工作创造条件-全面的知识库和使用单个产品服务的说明。
使用swagger文件
Selectel产品开发人员创建了一个API，并以草率格式将注释上传到代码中-这是* .yaml格式的文本文件，可用作代码。当API更新时，swagger文件也会更新，这使更新文档变得更加容易。
API文档使用以下技术解决方案：
- git存储库，带有* .yaml格式的大范围规范文件，按产品分组；
- git存储库，带有* .json格式的标准格式的翻译；
- git存储库，带有* .md格式的文件；
- * .md格式的文件包含文本描述，并包装在特殊的端点描述标签中，这些标签是从git存储库中提取的* .json格式的文件；
- 雨果静态网站生成器。
除了存储库的结构之外，还开发了使用存储库的规则：
- 已经准备了样式指南-Swagger文件的检查清单，开发人员在更新API规范时会检查该清单；
- git存储库的master分支（带有* .md格式的文件）反映了当前规范的状态，并且实际上在生产中；
- 当更新发布到生产环境中时，将执行向主分支的请求请求。
视觉组件
第一步是修改导航并创建规则，据此将形成知识库的各个部分。我们与UX设计人员一起准备了一个信息体系结构。该结构应尽可能透明，以使读者不要认为：“您在哪里可以找到本文？” 总结起来，有两种方法：
- 从界面。内容与面板的各个部分重复（单独用于服务）。在知识库的先前版本中就是这种情况。
- 从任务。文章和章节的标题反映了用户的任务。
为了简化结构，我们使用了这两种方法的组合。即使在带有深思熟虑的UX和UI的控制面板的较新版本中，也有必要至少解释这些术语，因为我们的产品技术复杂且用户差异很大。
除了更新目录之外，我们还改进了搜索和面包屑。 “面包屑”是用户到当前页面的路径，可以返回任何级别。在知识库的先前版本中，无法进入目录并且不方便，因此在新版本中我们对其进行了修复。
每个公司都根据自己对样式，结构和美感的看法制作API文档。如果我们打开不同公司的4-5个公共API，那么我们当然可以掌握一些共性：结构，大量的代码示例和语法突出显示，长页面。但是，所有示例都将具有特殊功能。例如，端点描述的本地化很少，而端点描述的结构通常看起来是相同的。
构造API文档的一些建议：
端点分组
除了提供每个端点的信息外，如果有很多端点，则最好将它们分组。一长串的端点列表使导航变得困难。
方法的单独描述
同时使用GET / POST方法时，一行中仅应描述一种方法。
也就是说，本例中的第一行是GET的描述，第二行是POST的描述，因此可以避免造成混淆。
进行更改的自动化
无需手动重新格式化每个部分即可简化更改-在我们的情况下，由于我们的devop专家已配置了此过程的自动化，因此我们仅翻译swagger文件的文本，而不会触及标记。
语法突出显示
开发人员最喜欢世界上的代码示例，没有开发人员会抱怨示例太多-他们大大减少了沉浸于产品中的时间。
当不同的元素根据编程语言进行适当的着色时，使用代码段会更加方便。
由于开箱即用的代码突出显示仅适用于深色背景，因此前端开发人员使用highlight.js将此解决方案修改为我们的公司样式。
而不是结论
自3月以来，更新的知识库已可供用户使用，而8月初以来也已提供了API文档。
“-与我们一起，当您长时间跑步时，您肯定会发现自己在另一个地方。我们已经做的只是改善知识库的又一步。我们将逐步向其他服务的API添加新的说明和文档。
“好吧，在这里，您知道，您必须以最快的速度跑到同一个地方，而到另一个地方，则需要以两倍的速度跑。”
（刘易斯·卡洛尔《爱丽丝梦游仙境》）