Kontentの使い方
カスタムドキュメントポータルの構築（すでに2つある場合）
By Jan Cerman
このシリーズの前回では、教材にサードパーティのソリューションを使用することの長所と短所について説明し、カスタムのサービスとしてのコンテンツベースのソリューションへの切り替えを検討するのに適した時期について説明しました。この記事では、KenticoKontent用の独自のドキュメントポータルを構築するプロセスと私たちが行った選択について説明します。
そもそもなぜCaaSなのか？
私たちは企業や個人にCMSソフトウェアを提供する会社です。これだけに基づいて、選択肢が与えられたときに、ドキュメント用にCMSを選択したと考えるのが安全です。それでも、Content-as-a-Serviceソリューションを資料のホームとして選択するという選択はすぐには行われませんでした。実際、それからはほど遠い。少し後、独自のポータルを構築するというアイデアが生まれた後、サイトを構築するためのいくつかの、主にマークダウンベースのツールを試しました。どのテクノロジーを使用し、どこにどのように材料を保管するかを決定する必要がありました。
既存の静的サイトジェネレーターのいくつかを検討し、ニーズに合わせて調整しました。動的コンテンツがほとんどまたはまったくない静的サイトよりも、ドキュメントポータルは何でしょうか。静的サイトを生成するための一般的なツールは、ほんの数例を挙げると、Jekyll 、 Hugo 、 Sphinx 、 DocFx 、GatsbyJsなど多くあります。私たちはこれらを試し、さらにいくつか試して、適切なものを見つけようとしました。しかし、どのツールを使用したかに関係なく、多くのことをカスタマイズする必要があることにすぐに気付きました。各ツールには、特定のテクノロジースタック（Node、React、Ruby、Pythonなど）とコンテンツを保存する方法（reStructuredTextまたは最新のマークダウンフレーバー）が付属しています。
私たちの資料を値下げするだけで十分であるように思われました。しかし、クロスリンク、再利用性、記事内のコードサンプルの参照、または少し標準的でないものについて考えれば考えるほど、通常のCMSを使用したほうがよいと思いました。コンテンツであるKenticoKontentを使用することにしました。 -as-a-Serviceソリューション。これは、後で教育資料のコンテンツハブになります。クロスリンクを処理し、コンテンツの再利用を容易にし、構造化されたコンテンツを通じて考えられるあらゆるものを作成できるため、これを選択しました。さらに、新しい人は、2つ以上ではなく1つのシステムの使い方を学ぶだけで済みます。
主な要件とビジョン
プロジェクト全体の背後にある私たちのビジョンは、単一のセルフサービスポータルを持つことでした。ユーザーが必要なものを簡単に見つけて、結果として成功したと感じることができるポータル。そのような単純な。しかし、私たちにはまだ長い道のりがありました。計画段階にあったとき、外部および内部の要件の長いリストがありました。顧客にとって最大の要件は、すべてを1か所で見つけられるようにすることでした。私たちにとって、要件の半分以上は、現在のサードパーティソリューションでこの領域に問題があったため、オーサリングエクスペリエンスに関連していました。いくつかの要件を挙げれば、次のことを行いました。
- 重複を避けるために、コンテンツを可能な限り再利用してください。
- コードサンプルをGitHub内に保存して、コードを1か所で管理し、開発者が新しいコードを準備できるようにします。
- 1ページのAPIリファレンスをより構造化された形式に再構築します。
また、ポータル自体のフィードバックメカニズムを通じて、またはCMSで直接、人々がドキュメントに貢献できるようにしたいと考えました。最後に、ポータルで何が起こっているのか、そしてポータルで人々が何をしているのかを知る必要がありました。つまり、Googleタグマネージャー、Amplitude、Hotjarなどの分析サービスと統合します。
あなたがあなたの材料について考える方法を再形成する
要件が決まったら、新しいCMS内でコンテンツをモデル化する方法を理解するときが来ました。多くの場合、CaaSソフトウェアにはWYSIWYGエディターがありません。これにより、プレゼンテーション（外観）とコンテンツ（記述方法）が分離された、マテリアルに関する新しい考え方に適応するように促されます。実装を開始する前に、マテリアルを確認し、いくつかのプロトタイプを作成しました。 CMSを使用して、新しいシステムでの実際の動作がどのようになるかを確認します。たとえば、画像、フォーマットされたテキスト、およびコールアウトを含む短い記事を作成するために必要なモデルを作成しました。この演習は非常にうまくいきました。次に、単純なコードサンプルを含むより複雑な記事を続けました。
より多くのプログラミング言語のコードサンプルを使用して記事に取り組むと、事態はさらに困難になりました。すべてのコードサンプルは、他の記事で簡単に再利用できる必要がありました。しかし、それだけではありません。また、読者が選択したテクノロジーに基づいて、異なる（または部分的に異なる）コンテンツを持つ可能性のある記事も必要でした。当時、私たちは約10のテクノロジー（たとえば、プレーンJavaScript、React、.Netなど）から選択することができました。ただし、ほとんどの技術記事は少数のテクノロジーを念頭に置いて作成されていたため、2回のプロトタイピングセッションが行われ、チーム内で検証が行われました。私たちは、過度に複雑なモデルをすぐに却下し、可能な限りシンプルにするよう努めました。物事をシンプルにすることは、プロジェクト全体を通して継続的なテーマになりました。可能な限りシンプルにすることを優先しました。
移行または実装が開始される前に、適切なモデルとアプローチを理解するために費やされた時間の投資により、新しいソリューションについての理解が深まりました。モデルを視覚的に説明することは、開発者にアイデアを提示するときに役立ちました。当時の既存の記事を紹介し、モデルのプロトタイプと並べて、個々のパーツを別々のコンポーネントに分解しました。すぐに、構造化されたコンテンツがすべての人にとって意味のあるものになり始めました。
スコープの定義
モデルがどのように見えるかを大まかに考えたとき、プロジェクト全体を成果物のパーツに分割する時が来ました。 CaaSの利点の1つは、繰り返しリリースして、各パーツが利用可能になり次第顧客に出荷できることです。このアプローチにより、ポータルが完全に完成する前に改善できた可能性があります。また、新しいソリューションを徐々に採用し、既存のコンテンツを一度にすべてではなく1つずつ移行します。Win-win。また、API参照を完全に異なるものに移行するために費やす時間を節約して、ダウンタイムなしで通常の作業を続行できました。 。しかし、それについては後で詳しく説明します。
サードパーティソリューションとカスタムソリューションの価値について説明している最初の記事を見逃した場合は、下の図の方がわかりやすいように、すぐに説明します。 2つの主要なペルソナのために2つの場所に資料がありました。これらは、2つのサードパーティのSoftware-as-a-Service（SaaS）ソリューションでした。それらはそれ自体でうまく機能し、私たちが最初に選択した目的のために、お客様のエクスペリエンス全体を断片化しました。 1つのフードの下ですべてに移動する時が来ました。この取り組みを通じて、すべてが機能し続けるようにする必要がありました。
プロジェクトを3つの主要なフェーズに分割します。各フェーズでは、資料のさまざまなセグメント（エンドユーザーガイド、開発者資料、APIリファレンス）を取り上げ、技術的な観点とコンテンツの観点から複雑さを増しました。リリース計画は次のようになりました。
1.エンドユーザーガイドを使用してポータルのコアを解放します。
- 使用した2つのソリューションのいずれかを完全に置き換えます。
- まだ2か所にドキュメントがあります。
- 推定時間：1ヶ月
2.コードサンプルと技術記事をポータルに追加します。
- 使用した他のサードパーティソリューションの半分を置き換えます。
- コードはGitHubで一元化されていますが、CMSはポータルの信頼できる唯一の情報源であり続けました。
- まだ2か所にドキュメントがあります。
- 推定期間：2ヶ月
3.API参照コンテンツをポータルに追加します。
- 他のサードパーティソリューションを完全に置き換えます。
- すべてが1か所にあります。
- 推定時間：2〜3ヶ月
ポータルの中核は、私たちにとって最小限の実行可能な製品でした。正しく検索し、エンドユーザーガイドを正しく表示し、信頼性を高める必要がありました。
APIドキュメントでセミカスタム化
私たちのAPIドキュメントは、すべてのAPIがくっついた単一の長いページでした。私たちの目標は、APIが分離されるようにドキュメントを再設計することでした。また、参考資料内のコードサンプルを強調表示し、コンテンツをまとめて表示する方法を簡素化したいと考えました。一般に、APIリファレンスコンテンツは高度に構造化されています。各APIにはいくつかの操作があり、各操作は少なくとも1つのオブジェクトを返し、各オブジェクトはプロパティのリストで構成され、各プロパティには独自のメタデータのセットがあります。再設計前に作成したAPIドキュメントには、これらの構造を説明するために作成された手動で作成されたテーブルが多数含まれていました。また、ご存じない場合は、テーブル、特にマークダウンの大きなテーブルは、操作および保守が面倒であることをお伝えします。プロジェクトのこの部分にどのようにアプローチするかを決めるとき、私たちは「最初からやり直す価値があるか」と自問しました。質問は少しの間空中に残り、APIドキュメント用に独自のビジュアルを設計および作成することをすぐに検討しましたが、答えは「そうではありません」でした。
APIドキュメントを生成できるツールを探し始めましたが、注目を集めたのはReDocでした。 ReDocは、フィードしたOpenAPI仕様に基づいてAPIリファレンスドキュメントを生成できます。これはすばらしいことです。唯一の問題は？ OpenAPI仕様はまだありません。私たちのリファレンスコンテンツは、4つのREST API、JavaScript API、およびいくつかの記事で構成されていました。すべて手動で記述され、サードパーティのSaaSソリューション内に保存されています。 OpenAPI仕様は、ドキュメント化の目的で必要なすべてをサポートしているように見えました。仕様に関するツールとコミュニティは非常に活発でした。さらに、仕様はコンテンツの再利用をサポートしていました。これは、KenticoKontent自体ですでに行っていたことです。ここまでは順調ですね。
ここで、OpenAPIに全面的に参加するという決定の問題は、オーサリングエクスペリエンスを断片化することを本質的に意味することでした。記事は、CMSでオーサリングされ、REST APIはOpenAPIを使用してオーサリングされ、GitHubに保存される可能性があります。突然、新しい質問が出てきました。 2つをどのようにリンクしますか？ 2人の間でコンテンツをどのように共有しますか？ 2つが同期したままになるように、リリースをどのようにスケジュールしますか？
前に概説した要件は、ここでも適用されます。それらを実現するには、計画を調整し、CMSのプロトタイピングモデルに戻る必要がありました。今回だけは、記事やコードサンプルではなく、KenticoKontent内のOpenAPI仕様をミラーリングすることでした。これは、12を超える新しいモデルと、CMSモデルと仕様の関係を概説したドキュメントを意味していました。幸い、OpenAPI仕様のすべての側面をカバーする必要はなく、RESTAPIを説明するために必要な部分だけをカバーする必要がありました。それでも、それは仕様が提供するものの約80％でした。次に、開発者は、コンテンツをCMSから各APIのOpenAPI仕様に変換する処理を行うために、いくつかのサービスを作成します。
それが私たちにもたらしたもの
オーサリングチームが学習曲線に取り組んだ後、私たちは以前にはなかったものを使い、楽しみ始めました。新しいバージョンを準備するためにコンテンツを複製する必要がなくなったため、新しいバージョンの記事を簡単に公開できるようになりました。コンテンツを特定の時間に公開するようにスケジュールを開始しました。特に、定期的にリリースされる環境で役立ちます。 Kentico Kontentのコメントにより、レビュープロセスも大幅に改善されました。これらにより、レビュー担当者はコンテンツの特定の部分にコメントし、オーサリング環境内でガイダンスを提供できます。これは、コンテキストの切り替えが少なくなり、フォーカスが増えることを意味します。また、特定のコンテンツを探す時間が少なくなるため、小さな変更の公開が2倍速くなりました。
すべての資料をまとめることで、あらゆるタイプのコンテンツ間でコンテンツを簡単にクロスリンクして再利用できます。これは、コールアウトなどの小さなコンテンツを作成し、記事やAPIリファレンス内で同様に使用できることを意味します。 CMSとポータルがそれを処理します。 APIリファレンスコンテンツをOpenAPIに変換することで、Postmanコレクションの生成を自動化し、時間を節約できます。さらに、標準化された仕様を使用してAPIを説明することで、私たちとお客様にとってより多くの統合シナリオへの扉が開かれます。
最後に、分析：ユーザーがサイトで何を探しているのか、どこで時間を費やしているのかがわかれば、その情報を使用して資料を継続的に改善し、時間をより適切に割り当てることができます。人々が何を検索し、それを見つけるかどうかについての良い考え。もしそうなら、それは良いことです。そうでない場合、それは行動の合図です。
次は何ですか？
プロジェクト全体を振り返ると、それは誰にとっても楽しい挑戦であり、学習体験でした。もう一度やらなければならない場合は、いくつか別の方法で行うと確信しています。それは旅の一部です。全体として、これまでのところ成果は素晴らしいものです。興味があり、詳細を知りたい場合は、このシリーズの次回の記事で、Kentico Kontent内のコンテンツモデリング、コンテンツバージョン管理、ローカリゼーション、およびコードサンプルの管理へのアプローチについて説明します。
