このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- Cloud Native Computing Foundation（CNCF）
- テクニカル ライター:
- Syam Sundar K
- プロジェクト名:
- 改善された Kubectl の例
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
このプロジェクトの目的は、既存の kubectl クイック リファレンスとリファレンス ドキュメントを強化することです。
このプロジェクトの最終的な目標は次のとおりです。 • より多くの優れた kubectl サンプルを作成する。 • kubectl クイック リファレンスに kubectl の例を追加しました。 • kubectl のドキュメントをリファクタリングして最大限に活用する。
目標 I - kubectl の例:
CLI の専門的関心グループと緊密に連携して、Kubernetes ユーザーがどのような例を最も求めているかを把握し、文書化します。これには、クイック リファレンスの既存の kubectl コマンドの改善からクイック リファレンスへの新しいコマンドの追加まで、多岐にわたります。
目標 II - ドキュメントの有用性の向上:
ドキュメントの有用性を高めるために、次のことを行います。
• 初心者の手間を省く • 論理フローの継続性を確保するために、kubectl コマンドを特定の順序で再配置する
コマンド / ユーザーケースの説明を改善することで、初心者の手間をなくします。簡単なことのようにも思えますが、初心者が学習を続けるかやめるかに大きく影響する可能性があります。たとえば、kubectl から Kubernetes を使い始めたときは、Pod と Deployment の違いがわかりませんでした。最初は Node.js で記述されたバックエンド サービスをデプロイしました。数時間後に停止したくて Pod を削除しようとしましたが、Pod の自己修復性が原因で、再作成されました。何が起きているのか戸惑ってしまい、なぜ再作成されたのに削除されないのか疑問に思っていました。ウェブで何度か調べたところ、Pod の削除は Deployment の削除と同じではないことがわかりました。熟練した目線では単純に見えるかもしれませんが、このような曖昧さをなくす明確な説明が、優れたドキュメントと優れたドキュメントを区別します。
論理フローの継続性を確保するために、kubectl コマンドを特定の順序で再配置しました。私のようにストーリーテリングを強く信じている人は、どうやってストーリーテリングの要素を終端コマンドのリストが入ったドキュメント シートに取り込むのでしょうか。私たちが学んできたものには、常に論理的な流れがあります。つまり、出発点と終点があるからです。コマンドライン ツールとしての kubectl は、当然のことながら習得に時間がかかります。実際、Kubernetes 自体の学習曲線と重なり合うことになります。ほとんどの人が kubectl から Kubernetes への移行を開始します（ウェブ UI を使用しているユーザーを除く）。また、kubectl の学習曲線は Kubernetes の学習曲線と密接に関連しているため、これらのコマンドの順序を変更し、ストーリーテリングの要素を導入するだけで、ドキュメントを大幅に改善できます。たとえば、水平 Pod 自動スケーリングなどの機能については、実際の例とイラストを使用してリソースを説明してから説明できます。
目標 III - ドキュメントのユーザビリティの向上:
最近の Kubernetes ウェブサイトを Docsy Hugo に移行したことは素晴らしい成果であり、ドキュメントの観点から大きな転換を遂げています。移行は成功しましたが、ドキュメントにはまだ多くの改善の余地があります。
いくつかの変更を提案しますが
• 左側のペインで、メインのドキュメントの現在アクティブなセクションまで自動的にスクロール - 現在のセクション、今後のセクション、過去のセクションを管理するのに役立ちます。 • クリップボードにコピー - コマンドの中には長くなるものがあります。この種のコマンドを使用する際にコピー機能は便利です。 • ドキュメント ファイルのコンテンツのフォーマット - 移行後、いくつかのページのコンテンツが適切な形式になっていません（例: kubectl の概要の「リソースタイプ」セクション）。これにより、ユーザー エクスペリエンスが低下します。
この変更により、Kubernetes ウェブサイトのユーザー エクスペリエンスが向上し、ユーザーの生産性も向上します。