このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- Cloud Native Computing Foundation（CNCF）
- テクニカル ライター:
- シュリーチ
- プロジェクト名:
- SMI と関連するサービス メッシュのドキュメントを改善
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
サービス メッシュ テクノロジーは基本的に、セキュリティ、管理、モニタリングのあらゆるニーズに対応することで、増加するサービスに価値を提供することを目的としています。サービス メッシュ インターフェース（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 Codelab と独立したユーザー ガイドを Jekyll の助けを借りて個別のユーザー チュートリアルを作成し、最後に API ドキュメントと統合して、エンドユーザーと今後の共同編集者の両方にバランスの取れたエクスペリエンスを提供する方法があります。
対象者: SMI プロジェクトは、その下のすべてのプロジェクトに、デプロイと運用のプラクティス、学習環境、パフォーマンス ベンチマークを提供します。個人と組織の両方を対象としています。
ユーザーガイド: 初心者のユーザーを対象とします。ユーザー側の IT の既存知識に関する前提はありません。対象: 初心者 理由: 主に広範なリファレンス ガイドとして使用されており、時間の経過とともに更新する必要がある。これには、ユーザーがサービス メッシュをセットアップして操作するために必要な情報がすべて揃っていることを確認するため、詳細な説明と役立つヒントが含まれます。必要に応じて動画、写真、スクリーンショット、GIF を追加することで、ガイドはさらに魅力的でユーザー フレンドリーになります。
ユーザー チュートリアル: 対象: 初心者向け 理由: ユーザーの注意を引き付け、ソフトウェアのテストをスムーズに実行できるように、魅力的なチュートリアルを作成することを目指しています。これにより、サービス メッシュ インターフェースの理解が深まります。
API エンドポイントのドキュメント: 対象: 上級ユーザー 理由: このセクションでは、サービス メッシュのより複雑な機能の使用に焦点を当てます。これは、基本的な IT の知識を持つ上級ユーザーを対象としています。 上級ユーザーは、必要に応じてリファレンス ガイドとしても使用できる簡潔なチュートリアルを探します。エンドポイントのドキュメントは、その正確性や一貫性を損なうことなく簡単に更新できるような方法で作成する必要があります。これは自動化プロセスであることが望ましいです。
リソース: ユーザー チュートリアル: Google Developers Codelab - インタラクティブで包括的なエンドユーザー チュートリアルの作成に使用します。 利点: - サンドボックスのチュートリアルを作成できる。- ハンズオン アプローチがある。 - Google ドキュメントを使用して記述され、マークダウン テキストをサポートしています。 - Google アナリティクスを使用してモニタリングできます。ユーザー トラフィックを簡単にモニタリングできます。 - 使いやすくてユーザーが直接投資せずにソフトウェアを直接操作できる、見た目に美しいチュートリアルを作成すること。
CLaaT（Codelabs as a Thing）プロジェクトを使用することで、Google Codelab を拡張し、簡単にデプロイできます。このプログラムは、マークダウンを使用して Google ドキュメントで記述されたチュートリアルを 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 Codelab を使用して、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 トラフィック分割も試して、サービス メッシュ構成にさまざまな検証ルールを実装しました。この学習プロセスは魅力的ですが非常に技術的なため、サービス メッシュ コミュニティへの第一歩を踏み出そうとしている、あるいは個人またはプロフェッショナルのプロジェクトでサービス メッシュを利用しようとしている新規ユーザーやデベロッパーにとっては、がっかりする可能性があります。私はこのギャップを埋めたいと考えています。これは、効率的で十分に文書化されたガイドとチュートリアルがないと達成できません。