このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。
プロジェクトの概要
- オープンソース組織:
- Cloud Native Computing Foundation（CNCF）
- テクニカル ライター:
- Syam Sundar K
- プロジェクト名:
- Kubectl の例をさらに追加
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
このプロジェクトの目的は、既存の kubectl の cheat sheet とリファレンス ドキュメントを拡張することです。
このプロジェクトの最終的な目標は次のとおりです。 • kubectl の例をさらに作成し、改善します。• kubectl クイック リファレンスに kubectl の例を追加しました。• kubectl のドキュメントをリファクタリングして、より役立つようにしました。
目標 1 - kubectl の例:
CLI の特殊団体と緊密に連携して、Kubernetes ユーザーがどのような例を最も必要としているのか、そのコンテキストを把握し、文書化します。クイック リファレンスの既存の kubectl コマンドの改善から、クイック リファレンスに新しいコマンドを追加するまで、さまざまな方法があります。
目標 II - ドキュメントの有用性の向上:
ドキュメントの有用性を高めるために、次のことができます。
• 初心者の苦労をなくす • kubectl コマンドを特定の順序に並べ替えて、論理フローに継続性を持たせる
コマンドやユースケースの説明を改善し、初心者の苦労を解消します。単純なことに思えるかもしれませんが、初心者が学習を継続するか中止するかに大きな影響を与える可能性があります。たとえば、kubectl で Kubernetes を始めたばかりの頃は、Pod と Deployment の違いがよくわかりませんでした。最初に、nodejs で記述されたバックエンド サービスをデプロイしました。数時間後に停止したかったので、Pod を削除しようとしましたが、Pod の自己修復機能により、Pod が再作成されました。何が起こっているのか、なぜ削除されずに再作成されるのか、理解に苦しんでいました。ウェブでいくつか検索した結果、ポッドの削除は Deployment の削除とは異なることがわかりました。熟練した目から見ると、これは単純に見えるかもしれませんが、この種のあいまいさを取り除く明確な説明が、優れたドキュメントと優れたドキュメントを区別するものです。
論理フローの連続性を保つために、kubectl コマンドを特定の順序で並べ替える。ストーリーテリングを重視する私のような人なら、ターミナル コマンドのリストが記載されたドキュメント シートにストーリーテリング要素をどのように組み込むのか疑問に思うかもしれません。しかし、それは可能です。私たちが学ぶあらゆるものには、常に論理的な流れがあります。それは、あなたが望むのであれば、開始点と終了点です。コマンドライン ツールとしての Kubectl には、当然ながら学習曲線があります。実際、その学習曲線は Kubernetes 自体の学習曲線と一致します。ほとんどのユーザーは kubectl から Kubernetes の使用を開始します（ウェブ UI を使用するユーザーを除く）。また、kubectl の学習曲線は Kubernetes の学習曲線と密接に関連しているため、これらのコマンドの順序を変更し、ストーリーテリング要素を導入するだけで、ドキュメントを大幅に改善できます。たとえば、水平 Pod 自動スケーリングなどの機能は、実際の例とイラストを使ってリソースを説明すると説明できます。
目標 III - ドキュメントのユーザビリティの改善:
Kubernetes ウェブサイトを Docsy Hugo に移行したのは素晴らしいことです。ドキュメントの視点が大きく変わりました。移行は成功しましたが、ドキュメント スペースにはまだまだ改善の余地があります。
以下に、おすすめの変更をいくつか示します。
• 左側のペインが、メインのドキュメントで現在アクティブなセクションに自動的にスクロールする - 現在のセクション、今後のセクション、過去のセクションを追跡するのに役立ちます。• クリップボードにコピー - コマンドの長さによっては、コピー機能が役立ちます。• ドキュメント ファイルのコンテンツ形式 - 移行後に、一部のページのコンテンツの形式が正しい形式になっていません（例: kubectl の概要の [Resource Type] セクション）。これにより、ユーザー エクスペリエンスが低下します。
これらの変更は、Kubernetes ウェブサイトのユーザー エクスペリエンスを向上させ、ユーザーの生産性を高めることができます。