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