Selectelヘルプセンター：インターフェイス、技術的な実装および機能

Selectelが提供する各サービスは、個人アカウント（コントロールパネル）で管理できます。当社の製品の多くは、APIリクエストを介して制御することもできます。製品の説明とAPIドキュメントは、単一のヘルプセンターで入手できます。



ヘルプセンターの主なアイデアは、クライアントが都合のよいときにいつでもSelectelサービスに関するほとんどの質問に対する回答を独自に見つける機会を提供することです。



次に、ドキュメントの作成方法を変更し、ナレッジベースの外観を更新した方法について説明します。



3年前のナレッジベースとそのビジュアルコンポーネントの技術的な実装は、情報を含むリファレンスブックのすべてのニーズを完全にカバーしていました。しかし、過去において、同社は立ち止まっておらず、新しいサービスの立ち上げと既存のサービスの開発の両方を積極的に行ってきました。



約1年前、既存のオンラインヘルプがお客様の要件を満たしていないことに気づきました。

• ナビゲーションメニューは、庭師の世話を知らない果物の木のように成長しました。
• 検索は便利ではなくなりました。
• ビジュアルデザインは徐々に時代遅れになりました。

以前は、当社の製品のAPIのドキュメントは公開されていませんでした。一部は、my.selectel.ruコントロールパネルに投稿され、一部はリクエストに応じて発行され、一部は完全にテキスト形式で記述され、最新の状態に保たれていました。非常に問題があります。これで、[ APIドキュメント]タブのITインフラストラクチャの自動化とSelectelサービスのバックエンドとの相互作用についての知識が得られました。

過去への小さな遠足

10年または15年前、ロシアでソフトウェアを製造している企業の中には、オンラインヘルプを自慢できるものはほとんどありませんでした。取扱説明書は、20世紀の70年代に作成されたGOSTを現代の絶えず変化する要件に適用しようと、常に変化するスタイルを使用してWord形式で作成されました。



ミームはまだテクニカルライターの間で人気があります：





今日まで、便利なサイトインターフェイスをすでに自慢できる企業がありますが、それらのドキュメントは「45枚のPDF形式のダウンロード手順」のレベルのままです。



大企業では、知識ベースは技術サポートと強く関連しています。真空状態の理想的な球形の世界では、ユーザーは技術サポートに連絡することなく、質問に対する回答の80％を独自に見つけることができるはずです。



ドキュメントのあるポータルは明確な利益をもたらしませんが、スクリプトにより技術サポート時間を節約できます。

1. ユーザーがサービスを注文しました。
2. セットアップ時に明白な瞬間に直面しました。
3. テクニカルサポートに連絡したかった。
4. ナレッジベースに行って、自分で必要な情報を見つけました。
5. テクニカルサポートに連絡しませんでした。
6. 利益！）

ヘルプ情報は、ユーザーが接続した後にのみサービスを理解するのに役立つという意見がよくあります。これはおそらく、Windowsでの作業に関する情報が記載された印刷された本が出版された時代に当てはまりました。しかし今では、購入前にサービスがどのように機能するかを潜在的なユーザーに公然と示すことも同様に重要になっています。





ほとんどのソフトウェア会社は、ある時点で内部使用と顧客の両方のためのAPIを開発しています。企業は、パブリックAPIをリリースすることで一連の入力を共有し、顧客がサービスを企業の製品と統合できるようにします。



既製のコードチャンクをコンストラクターとして使用して最もユーザーフレンドリーなインフラストラクチャを作成するなど、多くのカスタムタスクを自動化できます。しかし、それが何であるか、それが何をするのか、そしてそれをどのように使用するのかについての説明のないコードの断片はほとんど役に立ちません-あなたはメソッドが何であるか、そして彼らが入力することを期待するデータを見つけるために力ずくで言うことはありません。

-パブリックAPIを快適に使用するには、何をする必要がありますか？

-ドキュメントを添付してください！

APIのドキュメントとして、通常、メソッド（エンドポイントとも呼ばれます）を説明し、サービスからの応答を提供する、対話の最小限の例を示します。例えば、使用してKubernetesのAPIを、あなたは内のクラスタノードでの作業を自動化することができマネージドKubernetes。

私たちの前にあったタスク

私たちの視覚的な解決策は、必要な記事を簡単に見つけることをやめ、既存のメニューは読めない「シート」に変わりました。読めない文書は、無関係なテキストと同じくらい悪いです。人々はよくレイアウトされた資料を読むことに慣れています。ブログ、ソーシャルネットワーク、メディア-すべてのコンテンツは美しいだけでなく、読みやすく、見た目にも魅力的です。現在、特にそのような膨大な数のテキストの場合、UXとUIの要件を無視することはできません。



サイトのビジュアルデザイン技術の開発に伴い、ナレッジベースの外観が古くなっていることに気づきました。KB記事でアンカーとリストを使用するだけでは役に立ちませんでした。ドキュメントの構造全体と検索メカニズムを修正する必要がありました。

ドキュメントに関する一般的な問題

一般的に存在しないか、誰もその存在を知り

ません。見つからない命令は、存在しない命令よりも優れています。



この問題を次のように解決しました。毎月のメーリングリストに役立つ記事へのリンクを追加し、サイトの製品ページにトランジションを追加し、企業メッセンジャーの特別なチャネルを通じて、関心のあるすべての従業員に通知を設定しました。



古く、時間内に更新されていない

文書化プロセスは製品開発に組み込まれておらず、文書化は残りの基準で行われます。



私たちの場合、製品マネージャーは、新しい機能に取り組んでいる間、この新しい機能を文書化することも任務になっています。



ドキュメントは複雑で整理されていないため、問題の解決方法を技術サポートに依頼する方が簡単です。

ドキュメントのためにドキュメントを作成することは無意味であり、簡単にアクセスできる必要があります。ドキュメントを見つけるためのオプションが多ければ多いほど良いです。



ナレッジベースのセクションのデザインを完全に改訂しました。ユニバーサルテンプレートが機能しない場合もあったため、製品マネージャー、技術サポート、フロントエンド開発チームなど、すべての関係者と積極的にやり取りする必要がありました。



APIドキュメントをパブリックスペースに移動する

OpenAPI、Swagger、またはその他の生成ツールで生成されたAPIドキュメントを使用する際の問題の1つは、サイトの他の部分との複雑な統合です。ユーザーがすべての指示と記事に問題なくアクセスできる必要があります。エンドポイントが1つのビューに表示され、同じプロセスのテキスト説明が別のページに表示されると不便です。





単一の視覚的イメージの維持

単一のヘルプセンターを作成する場合、一連の「git + markdown + swagger」を使用して、指示と仕様の一貫した表示を維持する必要がありました。

今の仕組み

技術的な実装

ナレッジベースは元々、Confluenceと静的ページジェネレータの組み合わせを中心に構築されていました。



Confluenceを廃止し、Documentation-as-Codeに移りました。これで、ナレッジベースのすべてのソースコードがマークダウン形式でタイプセットされ、Gitバージョンのストレージシステムに保存されます。ナレッジベースサイトは、Hugo Static SiteGeneratorを使用してリポジトリから構築されます。



このサイトは、Gitリポジトリのmasterブランチに含まれているファイルから生成されます。データはプルリクエストを介してのみ更新できます。これにより、ドキュメントのすべての新しいセクションを、パブリックドメインで公開する前に確認できます。このようなシステムは、編集を行うためのアプローチも容易にします。会社の従業員はいつでもブランチを作成し、それに必要なすべての変更を追加できます。

コードとしてのドキュメントの詳細

「コードとしての文書化」の原則は、コードの作成と同じツールを文書の作成に使用することを意味します。

• テキストマークアップ言語;
• バージョン制御システム;
• コードレビュー。

このアプローチの主な目標は、最終結果に関するチーム全体の共同作業の条件を作成することです。これは、本格的な知識ベースと個々の製品サービスの使用方法です。

スワッガーファイルの操作

Selectel製品の開発者は、APIを作成し、コメントをスワッガー形式でコードにアップロードします。これは、コードとして使用できる* .yaml形式のテキストファイルです。APIが更新されると、swaggerファイルも更新されるため、ドキュメントの更新が簡単になります。



APIドキュメントには、次の技術ソリューションが使用されます。

• 製品ごとにグループ化された* .yaml形式のswagger仕様ファイルを含むgitリポジトリ。
• * .json形式のswagger仕様の翻訳を含むgitリポジトリ。
• * .md形式のファイルを含むgitリポジトリ。
• * .md形式のファイルにはテキストの説明が含まれ、特別なエンドポイントの説明タグでラップされます。これらのタグは、*。json形式のファイルとともにgitリポジトリから取得されます。
• Hugo静的サイトジェネレータ。

リポジトリの構造に加えて、リポジトリを操作するためのルールが開発されました。

• スタイルガイドが用意されています。これは、開発者がAPI仕様を更新するときにチェックするswaggerファイルのチェックリストです。
• * .md形式のファイルを含むgitリポジトリのマスターブランチは、現在の仕様の状態を反映しており、実際には本番環境にあります。
• マスターブランチへのプルリクエストは、アップデートが本番環境にリリースされたときに実行されます。

ビジュアルコンポーネント

最初のステップは、ナビゲーションを改訂し、ナレッジベースのセクションが形成されるルールを作成することでした。UXデザイナーと一緒に、情報アーキテクチャを準備しました。読者が「この記事はどこにありますか？」と思わないように、構造はできるだけ透明にする必要があります。要約すると、2つのアプローチがあります。

• インターフェイスから。コンテンツは、パネルのセクションを複製します（サービス用に個別に）。これは、以前のバージョンのナレッジベースの場合でした。
• タスクから。記事とセクションのタイトルは、ユーザーのタスクを反映しています。

構造を合理化するために、これら2つのアプローチを組み合わせて使用​​しました。 UXとUIがよく考えられた新しいバージョンのコントロールパネルでも、当社の製品は技術的に複雑でユーザーが大きく異なるため、少なくとも用語を説明する必要があります。



目次の更新に加えて、検索とブレッドクラムが改善されました。 「ブレッドクラム」は、現在のページへのユーザーのパスであり、任意のレベルに戻ることができます。以前のバージョンのナレッジベースでは、目次に入ることができず、不便だったため、新しいバージョンでは修正しました。



各企業は、スタイル、構造、および美意識に関する独自のビジョンに従ってAPIドキュメントを作成します。さまざまな企業の4〜5個のパブリックAPIを開くと、間違いなく、構造、膨大なコード例と構文の強調表示、長いページなど、いくつかの共通点を見つけることができます。それでも、すべての例には特別な機能があります。たとえば、エンドポイントの説明のローカリゼーションはまれですが、エンドポイントの説明の構造はほとんどの場合同じように見えます。



APIドキュメントを構成するためのいくつかの推奨事項：



エンドポイントのグループ化

各エンドポイントの情報を提供することに加えて、エンドポイントが多数ある場合は、それらをグループ化することが望ましいです。エンドポイントの長い連続リストは、ナビゲーションを困難にします。



メソッドの個別の説明

GET / POSTメソッドを同時に使用する場合は、1行に1つのメソッドのみを記述してください。



つまり、この場合の最初の行はGETの説明であり、2番目の行はPOSTの説明であるため、混乱を避けることができます。







変更の自動

化各セクションを手動で再フォーマットせずに変更を簡素化します。この場合、開発スペシャリストが構成したこのプロセスの自動化のおかげで、マークアップに触れることなく、スワガーファイルのテキストのみを翻訳します。



構文の強調表示

開発者はコード例を世界で最も愛しています。例が多すぎると不満を言う開発者はいません。製品に没頭する時間を大幅に短縮します。



プログラミング言語に応じてさまざまな要素に適切な色が付けられていると、コードの一部を操作する方がはるかに便利です。



すぐに使用できるコードの強調表示は暗い背景でのみ使用可能であったため、フロントエンド開発者は、highlight.jsを使用してこのソリューションを企業スタイルに変更しました。

結論の代わりに

更新されたナレッジベースは3月から利用可能になり、APIドキュメントは8月の初めから利用可能になりました。

「-私たちと一緒に、あなたが長い間走っているとき、あなたは確かに別の場所にいることに気づきます。

「まあ、ここでは、同じ場所にとどまるには同じくらい速く走らなければならず、別の場所に行くには2倍速く走る必要があります。」



（ルイス・キャロル「見るガラス越しのアリス」）

私たちがすでに行ったことは、知識ベースを改善するためのもう1つのステップです。他のサービスのAPIに新しい手順とドキュメントを徐々に追加していきます。