このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- Cloud Native Computing Foundation（CNCF）
- テクニカル ライター:
- Shriti
- プロジェクト名:
- SMI と関連するサービス メッシュのドキュメントを改善
- プロジェクトの長さ:
- 標準の期間（3 か月）
プロジェクトの説明
サービス メッシュ技術は、基本的に、セキュリティ、管理、モニタリングのすべてのニーズに対応することで、増加するサービスに価値を提供することを目的としています。Service Mesh Interface（SMI）は、サービス メッシュの最も一般的なユースケース（トラフィック ポリシー、テレメトリー、シフト）用の一連の API を定義し、サービス メッシュ間の互換性を実現します。サービス メッシュは、マイクロサービス環境でサービス間通信を処理するための専用のインフラストラクチャ レイヤです。これらのインターフェースの標準化により、エンドユーザー エクスペリエンスが向上するため、SMI と関連するサービス メッシュの将来の目標となっています。
現在の状態:
ユーザーガイド: SMI は比較的新しいサンドボックス プロジェクトで、2020 年 4 月に CNCF に寄付されました。その結果、プロジェクトにはエンドユーザー向けのドキュメントがありません。Meshery は、さまざまなサービスのパフォーマンス ベンチマークを備えたサービス管理プレーンで、さまざまなサービス メッシュのパフォーマンスの採用、構成、運用、管理を容易にします。また、任意のサービス メッシュ上で実行されているアプリケーションからの指標の収集と表示を組み込んでいます。そこで、SMI ユーザーコミュニティ全体の出発点となる、Meshery のガイドから始めましょう。
ユーザー チュートリアル: 既存の SMI プラットフォームでは、サンプル アプリケーションの Learn Layer5 が SMI の学習デバイスとして、また SMI 仕様の検証を行うサンプル アプリケーションとして機能しています。それ以外に、SMI プロジェクトにはエンドユーザー向けのチュートリアルがまったくありません。これは、プロジェクトの技術的な性質上、大きな障害となっています。Meshery は、SMI と関連するサービス メッシュのメリットと使用方法を示すのに最適なアプリケーションです。そのため、SMI の機能を示すベースツールとして使用します。
API ドキュメント: 現時点では存在しません。SMI と関連するさまざまなプロジェクトでは、API エンドポイントがプラットフォームで定義されています。たとえば、Meshery では、server.go（https://github.com/layer5io/meshery/blob/master/router/server.go）でエンドポイントが定義されていますが、外部で適切にコメントまたはドキュメント化されていません。この問題は、API の有用なドキュメントによって解決できます。また、ユーザーがエンドポイントをテストして機能をプレビューできる方法を追加することで拡張できます。
分析:
ユーザー チュートリアルは、ユーザーがソフトウェアを操作してテスト実行できるように作成されます。ユーザーの注意を引き付けるためには、インタラクティブで美しく、使いやすいものである必要があります。
ただし、ユーザーガイドは参照ガイドや問題の簡単な解決策として使用されることが多いので、ユーザーガイドの作成やホスティングには、より成熟した形式が推奨されます。インタラクティブではなく、明確性、一貫性、優れたユーザーフローを確保することに重点を置いて、適切に構成する必要があります。
解決策として、Google Codelabs を使用してユーザー向けチュートリアルを作成して、Jekyll を使用して独立したユーザーガイドを作成します。最後に、API ドキュメントとともに統合して、エンドユーザーと将来のコラボレーターの両方に包括的なエクスペリエンスを提供します。
対象読者: SME プロジェクトは、その傘下にあるすべてのプロジェクトにデプロイと運用のプラクティス、学習環境、パフォーマンス ベンチマークを提供します。個人と組織の両方に適しています。
ユーザーガイド: ユーザー側に IT に関する既存の知識があることを前提とせず、初心者ユーザーを対象とします。対象: 初心者 理由: 主に膨大なリファレンス ガイドとして使用されており、時間に合わせて更新する必要があります。これには、サービス メッシュの設定と操作に必要なすべての情報がユーザーに提供されるように、詳細な説明と役立つヒントが含まれます。必要に応じて動画、写真、スクリーンショット、GIF を追加することで、ガイドの魅力と使いやすさを高めています。
ユーザー チュートリアル: 対象: 初心者ユーザー 理由: ユーザーの注意を引き、ソフトウェアをスムーズにテストできるように、チュートリアルを魅力的で美しくすることに重点を置きます。これにより、Service Mesh インターフェースをより深く理解できるようになります。
API エンドポイントのドキュメント:対象: 上級ユーザー理由: このセクションでは、サービス メッシュのより複雑な機能の使用に重点を置いています。これは、基本的なレベルの IT 知識を持つ上級ユーザー向けの内容です。上級ユーザーは、必要に応じてリファレンス ガイドとして使用できる簡潔なチュートリアルを求めています。エンドポイントのドキュメントは、その精度や整合性を損なうことなく簡単に更新できるように、そのように記述する必要があります。可能であれば自動プロセスにしてください。
リソース: ユーザー チュートリアル: Google Developers Codelab - エンドユーザー向けのインタラクティブで包括的なチュートリアルを作成するために使用します。メリット: - サンドボックス チュートリアルを作成できます。 - 実践的なアプローチをとる。- Google ドキュメントを使用して記述され、マークダウン テキストをサポートしています。 - Google アナリティクスを使用してモニタリング可能 - ユーザー トラフィックを簡単にモニタリングできます。 - 使いやすい。ユーザーが直接投資することなくソフトウェアを直接操作できる、美しいチュートリアルを作成できます。
Google Codelab は、CLaaT（Codelabs as a Thing）プロジェクトを使用して拡張し、簡単にデプロイできます。これは、Google ドキュメントで Markdown を使用して記述されたチュートリアルを Codelab（HTML）形式に変換するために使用されるコマンドライン ツールを提供するプログラムです。
ユーザーガイド: Jekyll - meshery.io の既存のドキュメント（こちら）は Jekyll でホストされており、Docsy Jekyll テーマを使用しています。Markdown、liquid、HTML、CSS を使用して、ホスト可能な静的ウェブサイトを生成します。Ruby 開発環境で実行されます。メリット: - GitHub リポジトリからサイトを直接ホストできます。- 非常に活発なコミュニティで、十分にサポートされたプロジェクトです。 - 既存の SMI と Meshery のドキュメントに、ユーザー ガイドと拡張機能を追加するだけで、別のプラットフォームへの移行に煩わされることはありません。
API ドキュメント: Swagger（代わりに Swaggo）を使用して、SMI と Meshery の API ドキュメントを作成します。これは、API ドキュメントの作成に優れたソリューションです。メリット: - API 設計からのドキュメント: API の進化に伴ってドキュメントが最新の状態に保たれます。- API 設計からのドキュメント: API 定義から自動生成できます。 - 複数のドキュメント バージョンを維持する - カスタマイズされた API 設計
プロジェクトの目標: - Google Developer Codelabs を使用して、Meshery をツールとして使用し、SMI と関連するサービス メッシュのインタラクティブなエンドユーザー チュートリアルを作成します。- サービス メッシュに Jekyll を使用してエンドユーザー ガイドを作成します。- Swagger を使用して、SMI の API エンドポイントのドキュメントを生成します。- プロジェクトをコミュニティ主導型にすることで、将来のユーザーや現在のユーザー、デベロッパーが SMI コミュニティのガイダンスとモデレーションの下で、簡単に追加を続けられるようにします。
タイムライン: 提案されているタイムラインは、https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl で確認できます。
構成: ユーザーガイドの構成案については、こちらをご覧ください。 https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
このプロジェクトの目的サービス メッシュ コミュニティは、最近 CNCF にサンドボックス プロジェクトとして統合されたことで、急速に拡大しています。ただし、このプロジェクトでは、エンドユーザーとデベロッパーの両方にとってドキュメントが不足しています。私はこれまで、EmojiVoto アプリの linkerD、bookinfo アプリケーションを備えた Istio、Hashicorp の Consul など、さまざまなサービス メッシュを試してきました。また、SMI トラフィック分割も試し、サービス メッシュ構成にさまざまな検証ルールを実装しました。学習プロセスは魅力的ですが、高度な技術を必要とするため、サービス メッシュ コミュニティへの第一歩を踏み出そうとしている新規ユーザーや、個人または職場のプロジェクトでサービス メッシュを利用しようとしているデベロッパーにとっては、敬遠される可能性があります。このギャップを埋めるために、効率的でよく文書化されたガイドとチュートリアルを作成しました。