Scalar製品ドキュメントサイトの紹介
この内容はGoogle翻訳により翻訳されております。
Scalarでは最近、各製品の製品ドキュメントサイトを立ち上げました。各ドキュメントサイトへのリンクについては、Scalar Documentationを参照してください。
このブログ投稿では、私たちの目標、製品ドキュメントサイトの開発とホストの方法、実装したいくつかの機能、および将来実装したいその他の機能について説明します。
概要
私たちの目標は、製品ごとに分離された検索とナビゲーションのエクスペリエンスを備えたドキュメントサイトを開発することでした。ユーザーが使用している製品に固有のドキュメントを表示したいため、この分離は重要です。
ドキュメントサイトを設計するとき、各製品ドキュメントサイトがWebサイトや他のブランドコンテンツと同様の外観と雰囲気を持つようにしたいと考えました。さらに、製品の各バージョンのドキュメントを確実に提供できるようにしたいと考えました。
製品ドキュメントサイトをどのように開発およびホストしたか
コンテンツは異なりますが、同じユーザーエクスペリエンスを提供する一連の製品ドキュメントサイトを実現するために、Scalar製品ごとに個別のドキュメント専用リポジトリをセットアップすることにしました。
私たちは静的サイトジェネレーターとしてJekyllを使用し、Scalarブランドに合わせてテーマを大幅にカスタマイズし、バージョン管理されたドキュメントなどの機能を追加することにしました。Scalarのブランドに合わせてテーマを調整し、機能を追加するために、HTML、CSS、Markdown、Liquid、YAMLの知識を応用しました。
製品ドキュメントサイトのホスティングには、JekyllをネイティブにサポートするGitHub Pagesを使用します。製品ドキュメントサイトを迅速に公開したいと考えていたため、この側面は重要でした。現在のニーズにはGitHub Pagesで十分ですが、ニーズが拡大し、ドキュメントのエクスペリエンスを改善し続けるにつれて、他のオプションも念頭に置く必要があります。
各Scalar製品のドキュメントサイト
前述したように、Scalar製品ごとにドキュメント専用のgitリポジトリを作成しました。これらのリポジトリから、独自の製品ブランドのサブドメインを使用して、Jekyllベースの各ドキュメントサイトを展開します。
各ドキュメントサイトには、ソースコードリポジトリのオリジナルドキュメントが含まれており、製品ごとに個別のリポジトリに編成されています。たとえば、docs-scalardbリポジトリはScalarDB Enterpriseドキュメント専用であり、docs-scalardlリポジトリはScalarDL製品ドキュメント専用です。
ドキュメントサイトを製品ごとに分離することで、検索とサイドナビゲーションを通じて情報検索プロセスを合理化し、最適化されたドキュメント エクスペリエンスを提供できます。
企業顧客およびオープンソースコミュニティ向けのScalarDBドキュメント
各製品の製品ドキュメントサイトに加えて、ScalarDBの2つのドキュメントサイトもあります。
- ScalarDB Enterprise: 商用ライセンスまたは従量課金制モデルのサブスクリプションが必要です。
- ScalarDB Community: 無料のオープンソース製品です。
ScalarDB Enterpriseについては、有料顧客向けの堅牢な機能とさまざまな導入方法をカバーする包括的なドキュメントセットを用意しています。 ScalarDB Communityには、製品のオープンソースバージョンで利用できる機能に適用されるドキュメントがあります。
両方の製品タイプのドキュメントを分離することで、ScalarDBのオープンソースバージョンのユーザーに関連するコンテンツが確実に表示されます。
ドキュメントサイトを製品ごとに分離することで、検索とサイドナビゲーションを通じて情報検索プロセスを合理化し、最適化されたドキュメントエクスペリエンスを提供できます。
製品バージョンごとにドキュメントを参照できます
私たちのアーキテクチャの注目すべき点は、バージョン管理機能です。
ドキュメントリポジトリでは、フォルダを使用してドキュメントのバージョンを保存する簡単な方法を考案しました。ブランチやプラグインに依存するいくつかのアプローチとは異なり、この方法ではドキュメントのバージョンの更新が簡素化され、ユーザーにシームレスなバージョン選択エクスペリエンスが提供されます。
さらに、検索結果の範囲を柔軟に指定できるため、ユーザーは最新の製品バージョンのドキュメントのみを参照できるようになります。これにより、すべての製品バージョンの検索結果を表示する場合と比較して、混乱が最小限に抑えられます。将来実装できる可能性がある代替方法としては、ユーザーが検索を実行するときに特定のバージョンを選択できる機能を開発することです。
まとめ
Scalar製品ドキュメントサイトを立ち上げ、それらのサイトのコンテンツが定期的に更新されるようにするためのプロセスを実装したので、ドキュメントエクスペリエンスを引き続き改善する必要があります。
将来実装する予定の機能には次のようなものがあります。
- サイドナビゲーションの拡張および折りたたみ可能なセクション
- 明暗モード
- コードブロックのコピーボタン
さらに、ユーザーが製品を最大限に活用できるように、ドキュメントの包括的な再編成と改訂に取り組み始めました。
