Cette page contient les détails d'un projet de rédaction technique accepté pour 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:
- Exemples supplémentaires et améliorés de kubectl
- Durée du projet:
- Durée standard (3 mois)
Project description
L'objectif de ce projet est d'améliorer l'aide-mémoire kubectl et les documents de référence existants.
Voici les objectifs ultimes de ce projet : • Créer davantage d'exemples kubectl plus performants. • Ajouter des exemples kubectl à l'aide-mémoire kubectl • Refactoriser les documents kubectl pour une utilité maximale.
Objectif 1 - Exemples pour kubectl:
Nous allons travailler en étroite collaboration avec les groupes de personnes ayant des intérêts communs dans la CLI afin de déterminer les types d'exemples que les utilisateurs de Kubernetes attendent le plus et de les documenter dans leur contexte. Il peut s'agir d'améliorer les commandes kubectl existantes de l'aide-mémoire ou d'ajouter de nouvelles commandes à l'aide-mémoire.
Objectif II - Meilleure utilité des documents:
Pour améliorer l'utilité de ces documents, procédez comme suit:
• Éliminer les problèmes de débutant • Réorganiser la commande kubectl dans un certain ordre pour assurer la continuité du flux logique
Éliminez les problèmes de débutant grâce à de meilleures explications sur les commandes / cas utilisateur. Cela peut sembler simple, mais peut considérablement inciter les débutants à poursuivre ou à abandonner leur apprentissage. Par exemple, lorsque j'ai commencé à utiliser Kubernetes avec kubectl, je ne connaissais pas les différences entre les pods et les déploiements. Au début, j'ai déployé un service de backend écrit en Node.js. Au bout de quelques heures, j'ai voulu le faire disparaître. J'ai donc essayé de supprimer le pod, mais en raison de la nature autoréparable des pods, ils ont été recréés. J'étais un peu déconcerté par ce qui se passait et je me demandais pourquoi il était recréé et n'était pas supprimé. Après quelques recherches sur le Web, j'ai réalisé 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 ce genre d'ambiguïté 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 qui contient une liste de commandes de terminal. Je dis que 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 voulez. En tant qu'outil de ligne de commande, kubectl a évidemment une courbe d'apprentissage qui coïncide avec celle de Kubernetes. Presque tout le monde commence à utiliser Kubernetes avec kubectl (à l'exception de ceux qui utilisent l'interface utilisateur Web), et comme sa courbe d'apprentissage est étroitement liée à celle de Kubernetes, il est possible d'améliorer considérablement les documents en modifiant l'ordre de ces commandes et en y introduisant des éléments de narration. Pour une instance, vous pouvez expliquer des fonctionnalités telles que l'autoscaling horizontal des pods après avoir expliqué les ressources à l'aide d'exemples et d'illustrations concrets.
Objectif 3 : Amélioration de la convivialité de Google Docs :
La migration récente du site Web Kubernetes vers Docsy Hugo est géniale et constitue un changement majeur dans la perspective des documents. La migration a abouti, mais de nombreuses améliorations peuvent encore être apportées à l'espace dédié aux documents.
Voici quelques changements que je suggérerais,
• Le volet de gauche défile automatiquement jusqu'à la section active dans les documents principaux. Cela peut s'avérer utile pour garder une trace des sections en cours, à venir et passées. • Copier dans le presse-papiers : certaines commandes peuvent être longues. La fonctionnalité de copie peut s'avérer utile lorsque vous utilisez ce type de commandes. • Mise en forme du contenu des fichiers de document : après la migration, le contenu de certaines pages n'est pas mis en forme correctement. Exemple : section "Resource Type" (Type de ressource) dans la présentation de kubectl. Cela nuit à l'expérience utilisateur.
Ces modifications peuvent améliorer l'expérience utilisateur sur le site Web de Kubernetes et booster la productivité des utilisateurs.