Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Cloud Native Computing Foundation (CNCF)
- Rédacteur technique:
- Syam Sundar K
- Nom du projet:
- Plus d'exemples de kubectl et de meilleurs exemples
- Durée du projet:
- Durée standard (trois mois)
Project description
L'objectif de ce projet est d'améliorer la fiche récapitulative et les documents de référence kubectl existants.
Voici les objectifs ultimes de ce projet : • Créer plus d'exemples kubectl et les améliorer. • Ajout d'exemples kubectl à l'aide-mémoire kubectl. • Réfactorisation des documents kubectl pour une utilité maximale.
Objectif I : Exemples pour kubectl :
Je vais travailler en étroite collaboration avec les groupes d'intérêt spéciaux de la CLI afin de comprendre le contexte, de savoir quels types d'exemples les utilisateurs de Kubernetes souhaitent le plus et de les documenter. Il peut s'agir d'améliorer les commandes kubectl existantes dans l'aide-mémoire ou d'y ajouter de nouvelles commandes.
Objectif II : rendre les documents plus utiles :
Pour rendre les documents plus utiles, vous pouvez:
• Éliminer les difficultés des débutants • Réorganiser la commande kubectl dans un certain ordre pour assurer la continuité du flux logique
Éliminez les difficultés des débutants grâce à de meilleures explications sur les commandes et les cas d'utilisation. Cela peut sembler simple, mais cela peut avoir une influence significative sur la poursuite ou l'abandon de l'apprentissage par les débutants. Par exemple, lorsque j'ai commencé à utiliser Kubernetes via kubectl, je ne connaissais pas la différence entre les pods et les déploiements. Au départ, j'ai déployé un service backend écrit en nodejs. Après quelques heures, je voulais l'arrêter. J'ai donc essayé de supprimer le pod, mais en raison de la nature d'autoréparation des pods, ils ont été créés à nouveau. Je ne comprenais pas ce qui se passait et je me demandais pourquoi il était recréé et non supprimé. Après quelques recherches sur le Web, j'ai compris que supprimer des pods n'était pas la même chose que supprimer un déploiement. Pour un œil averti, cela peut sembler simple, mais une explication claire qui élimine ces types d'ambiguïtés est ce qui distingue un bon document d'un excellent document.
Réorganiser la commande kubectl dans un certain ordre pour assurer la continuité du flux logique. Si, comme moi, vous croyez fermement en la narration, vous vous demanderez probablement comment intégrer des éléments de narration dans une feuille de document contenant une liste de commandes de terminal. Je dis, c'est possible. Tout ce que nous apprenons a toujours un flux logique - un point de départ et un point d'arrivée, si vous le souhaitez. En tant qu'outil de ligne de commande, kubectl présente évidemment une courbe d'apprentissage. En fait, sa courbe d'apprentissage coïncide avec celle de Kubernetes elle-même. Comme presque tout le monde commence son parcours avec Kubernetes via kubectl (sauf les personnes qui utilisent l'UI Web) et que sa courbe d'apprentissage est étroitement liée à celle de Kubernetes, les documents peuvent être considérablement améliorés simplement en modifiant l'ordre de ces commandes et en y introduisant des éléments de storytelling. Par exemple, des fonctionnalités telles que l'autoscaling horizontal des pods peuvent être expliquées après avoir présenté les ressources à l'aide d'exemples et d'illustrations concrets.
Objectif III : Amélioration de la convivialité de Docs
La migration récente du site Web de Kubernetes vers Docsy Hugo est géniale et représente un changement majeur dans la perspective de la documentation. Bien que la migration ait réussi, de nombreuses améliorations peuvent encore être apportées à l'espace dédié aux documents.
Voici quelques exemples de changements
• Le volet de gauche défile automatiquement jusqu'à la section actuellement active dans les documents principaux. Cela peut être utile pour suivre les sections actuelles, à venir et passées. • Copier dans le presse-papiers : certaines commandes peuvent être longues. La fonctionnalité de copie peut être utile lorsque vous travaillez avec ce type de commandes. • Mise en forme du contenu des fichiers DOC: après la migration, le contenu de certaines pages n'est pas mis en forme correctement (par exemple, la section "Type de ressource" dans la vue d'ensemble de kubectl). Cela dégrade l'expérience utilisateur.
Ces modifications peuvent améliorer l'expérience utilisateur sur le site Web de Kubernetes et augmenter sa productivité.