このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- gRPC-Gateway
- テクニカル ライター:
- iamrajiv
- プロジェクト名:
- gRPC-Gateway の既存のドキュメント サイトのリファクタリング
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
概要:
ユーザー向けドキュメント サイトは、エンドユーザーがプロダクトやサービスを使用できるように設計されています。優れたユーザー ドキュメント サイトは、ユーザーがソフトウェアの使用方法、機能、ヒント、コツを学び、ソフトウェアの使用時に遭遇する一般的な問題を解決する方法を提供するため、非常に重要です。また、サポート費用を削減でき、製品の企業アイデンティティの一部にもなります。優れたユーザー ドキュメント サイトは、プロダクトであるデベロッパー チームが健全な状態であることの証です。優れたユーザー向けドキュメント サイトがないと、ユーザーは上記の作業を効果的かつ効率的に行う方法を把握できない可能性があります。ユーザー向けドキュメント サイトは、プロダクトの成功を左右する重要な役割を果たします。優れたコミュニケーションは、ビジネスやプロダクトの中心であり、今後もそうであり続けるからです。優れたドキュメントは、そのコミュニケーションを、誰もがアクセスして成功を収めることができる管理可能なフレームワークにまとめます。
本書の執筆時点では、gRPC-Gateway リポジトリは約 1, 200 回フォークされ、184 人がこのリポジトリに貢献しています。これは、世界中の多くの人が gRPC-Gateway を使用しており、gRPC-Gateway の使用方法に関するガイダンスについてユーザー ドキュメントを参照したくなる可能性があることを示しています。ただし、gRPC-Gateway のユーザー ドキュメントとドキュメント サイトは現在古く不完全であるため、gRPC-Gateway コミュニティはこのプロジェクトを使用して既存のドキュメント サイトをリファクタリングし、ドキュメント サイトを改善し、エンドユーザーが gRPC-Gateway を使用する際にシームレスなエクスペリエンスを提供したいと考えています。
現在の状態:
現在、gRPC-Gateway のドキュメント サイトには大きな問題が 2 つあります。
• 最初の問題は、ドキュメント ウェブサイトが不適切で古いことです。サイトのスタイルと構造、使用されているテーマが古く、不完全で、ナビゲートや情報の検索が難しく、優れたドキュメント ウェブサイトの多くの機能が網羅されていません。gRPC-Gateway の既存のドキュメント サイトのリファクタリングには、ウェブサイトのスタイル設定、ドキュメント検索などの機能の追加、ウェブサイトの UI の改善、チュートリアルと例を適切なサイドバーに整理すること、新しいフローチャートを設計して既存のフローチャートを更新することなどが含まれます。これが私の主な目標であり、私の作業は既存のドキュメント サイトのスタイル設定と再構築に重点を置いています。
• 2 つ目の問題は、gRPC-Gateway の既存のドキュメント、チュートリアル、サンプルなどをリファクタリングする必要があることです。これは、ファイル内の誤字脱字や文法上の誤りを削除し、Go スニペットを適切に配置し、Gofmt 形式に従って Go スニペットをリファクタリングすることで行えます。また、必要に応じてドキュメント、チュートリアル、例を追加したり、既存のファイルをリファクタリングして再利用したりできます。2 つ目の目標は、既存の Google ドキュメント サイトのスタイル設定と再構築という主要目標を達成した後に行う。
提案されたドキュメント サイトが現在のドキュメント サイトよりも改善されているのはなぜですか？
提案されているユーザー向けドキュメント ウェブサイトは、エンドユーザーの効率性、一貫性、安心感を高め、確保するように構成されます。セクションや機能に適切なスタイルを適用し、ガイドと関連するフローチャートと画像を追加することで、UI の外観が改善されます。
gRPC-Gateway のドキュメントでは、この方法と例が詳しく説明されています。まだ古い Jekyll のテーマが使用されており、最近では SSG（Static Site Generator）の Jekyll テーマも優れています。また、ページの構造を変更し、新しい例やチュートリアルを追加して、以前のコンテンツを更新、書き直し、ユーザーにとってより有用なものにする必要があります。
提案された目標とアイデアの構造とロードマップ:
本プロジェクトの主要目標:
上記の目標とアイデアは、次の方法で実装できます。
現在の Jekyll テーマを、より優れた堅牢なテーマに変更しました。再度 Jekyll テーマを使用する理由は、新しい Jekyll テーマに似た既存の Jekyll フレームワークとテーマをすでに把握しているため、メンテナンス担当者がプロジェクトのワークフローに貢献し、理解しやすくなるからです。
インターネットでさまざまな Jekyll テーマを調べた結果、次の機能があるため、https://idratherbewriting.com/documentation-theme-jekyll/ のテーマ スイートが gRPC-Gateway のドキュメント サイトに最適であることがわかりました。
• Markdown:-技術ライターがインストールについて心配する必要がないようにします。.md ファイルに簡単に記述できます。誰でも、ウェブサイトに表示される編集ボタンをクリックして（新機能）、改善を加えるために投稿（GitHub のページの編集や変更の提案）することができます。これにより、ユーザーは新しいコンテンツを追加したり、コンテンツを編集して改善したりするようになります。
• ドキュメント検索:- ユーザーが関連するコンテンツをすばやく簡単に見つけられるように、検索ボックスが必要です。
• コメント セクション:- ユーザーは、投稿やチュートリアルにコメントを残したり、自分の意見を共有したりすることができます。プロジェクト ドキュメントの他のユーザービューを読むことができます。
• 新しいリリースノートおよびブログ:- ウェブサイトを更新し、新しいブログ投稿と、現在の開発とロードマップに関する最新情報を掲載する必要があります。そのため、ランディング ページにブログを掲載する必要があります。
• 迅速な開発:- SSG（静的サイト ジェネレータ）フレームワークのほとんどはサーバーで実行され、ファイルの変更は UI にすぐに反映されます。また、デプロイとビルドのプロセスも簡単である必要があります。今後、フレームワークを変更する場合は、これで簡単にできます。ほとんどのフレームワークは Markdown の記述をサポートしているため、.md ファイルを移動して少し変更するだけで十分です。
ここでは、既存のウェブサイトのページを新しいウェブサイトのセクションとページに分割します。
• ランディング ページ:-
ランディング ページには、gRPC-Gateway の主な機能について記載する必要があります。
- gRPC-Gateway のスタートガイド（ユーザーガイドにリダイレクト）
- 簡単なインストール手順（簡単なコマンド）
- gRPC-Gateway を使用する理由
- gRPC-Gateway を使用するプロジェクト
そのため、長い説明文を書くのではなく、ランディング ページに主なポイントを表示し、詳細を確認するためのリンクを提供するというのが基本的な考え方です。
• gRPC-Gateway ユーザーガイド ページ:-
- インストール ガイドをご覧ください。
- gRPC-Gateway のクイックスタート。
• gRPC-Gateway デベロッパー ガイドのページ:-
開発ガイド、コントリビューション ガイド、Git の設定、行動規範、ドキュメントの設定、開発ワークフローなど、内部の類似ページを参照しています。そのため、すべてのファイルのリファクタリングと並べ替えが必要になります。メインの開発ページには、これらのページがすべて含まれ、各ステップでハイパーリンクが作成されます。
• gRPC-Gateway のページについて:-
すべてのコントリビューターのリストをチームのセクションに配置する必要があります。 クイックリンクとリリースノート、最新のブログを追加して、ユーザーに gRPC-Gateway の最新のニュースを読ませてもらうことができます。
• ブログ、リリースノート、チュートリアルのページ:-
ウェブサイトにはブログ オプションが必要です。そのため、ニュースやリリースを簡単に伝えることができます。チュートリアル ページには、gRPC-Gateway API とコンセプトを明確にする人気のある講演や記事がいくつか含まれています。コントリビューターは、チュートリアル ページでチュートリアルのリンクを追加できます。
上記のタスクを完了したら、v2 ブランチで同じ変更を更新し、gRPC-Gateway のマスターブランチと合わせます。
このプロジェクトの副次的な目標:-
gRPC-Gateway のドキュメントをより堅牢で読みやすくするために、他の変更も行う必要があります。
• gRPC-Gateway の既存のすべてのファイルで、文法上の誤りやスペルミスを修正し、サイト内のリンクと投稿を整理して調整しました。
• gRPC-Gateway で必要に応じてドキュメントとコンテンツを追加します。ほとんどの機能は、AWS 上のサイトのドキュメント セクション、バックグラウンドと使用方法など、非常に短いドキュメントです。
• Gofmt 形式に従って Go スニペット gRPC-Gateway をリファクタリング
上記のタスクを完了したら、v2 ブランチで同じ変更を更新し、gRPC-Gateway のマスターブランチと合わせます。
私がこのプロジェクトに適している理由:
私がこのプロジェクトに適任である理由は次のとおりです。
• 組織のドキュメントの改善に携わった経験があり、任意のバージョン管理システムを使用できるため、GitHub でコマンドを実行しても問題ありません。• さらに、人々に価値をもたらすプロジェクトに携わることが私の原動力です。 誰かにできるだけ効率的な方法で何かをしてもらいたい場合は、それを文書化するのが一般的です。プロセスを文書化することで、効率性、整合性、関係者全員の安心感を確保できます。• 過去 2 か月間 gRPC-Gateway に貢献し、11 件の PR を統合したため、gRPC-Gateway のワークフローとコードベースに精通しています。