En esta página, se incluyen los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- Cloud Native Computing Foundation (CNCF)
- Redactor técnico:
- Syam Sundar K
- Nombre del proyecto:
- Más y mejores ejemplos de kubectl
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
El objetivo de este proyecto es mejorar la hoja de referencia y los documentos de referencia existentes de kubectl.
Estos son los objetivos finales de este proyecto: • Crear más y mejores ejemplos de kubectl. • Se agregaron ejemplos de kubectl a la hoja de referencia de kubectl. • Se refactorizaron las docs de kubectl para que sean más útiles.
Objetivo I: Ejemplos de kubectl:
Trabajará en estrecha colaboración con los grupos de interés especial de la CLI para obtener el contexto de qué tipo de ejemplos quieren más los usuarios de Kubernetes y documentarlos. Esto puede ir desde mejorar los comandos kubectl existentes en la hoja de referencia hasta agregar comandos nuevos.
Objetivo II: Aumentar la utilidad de los documentos:
Para aumentar la utilidad de los documentos, se puede hacer lo siguiente:
• Elimina las dificultades de los principiantes. • Reorganiza el comando kubectl en un orden determinado para garantizar la continuidad en el flujo lógico.
Elimina las dificultades de los principiantes con mejores explicaciones de comandos o casos de uso. Esto puede parecer simple, pero puede influir de manera significativa en los principiantes para que continúen o abandonen su aprendizaje. Por ejemplo, cuando comencé a usar Kubernetes a través de kubectl, no estaba seguro de las diferencias entre los pods y las implementaciones. Inicialmente, implementé un servicio de backend escrito en nodejs. Después de unas horas, quise bajarlo, así que intenté borrar el pod, pero debido a la naturaleza de autorecuperación de los pods, se volvieron a crear. No entendía qué estaba pasando y me preguntaba por qué se volvía a crear y no se borraba. Después de algunas búsquedas en la Web, descubrí que borrar Pods no es lo mismo que borrar una implementación. Para un ojo entrenado, esto puede parecer simple, pero una explicación clara que elimine este tipo de ambigüedades es lo que distingue un buen documento de uno excelente.
Reorganizar el comando kubectl en un orden determinado para garantizar la continuidad del flujo lógico Si eres como yo y crees firmemente en la narración de historias, es probable que te preguntes cómo incorporar elementos de narración en una hoja de documentos que tiene una lista de comandos de la terminal. Te digo que se puede hacer. Todo lo que aprendemos siempre tiene un flujo lógico: un punto de partida y un punto final, si quieres. Kubectl, como herramienta de línea de comandos, obviamente tiene una curva de aprendizaje, de hecho, su curva de aprendizaje coincide con la de Kubernetes. Dado que casi todos comienzan su recorrido con Kubernetes a través de kubectl (excepto las personas que usan la IU web) y su curva de aprendizaje está estrechamente vinculada con la de Kubernetes, los documentos se pueden mejorar significativamente con solo cambiar el orden de estos comandos y agregar elementos de narración. Por ejemplo, las funciones como el escalamiento automático horizontal de pods se pueden explicar después de explicar los recursos con ejemplos e ilustraciones del mundo real.
Objetivo III: Mejoras en la usabilidad de Documentos:
La migración reciente del sitio web de Kubernetes a Docsy Hugo es increíble y representa un cambio enorme en la perspectiva de la documentación. Aunque la migración se realizó correctamente, aún hay mucho margen de mejora en el espacio de documentos.
Estos son algunos de los cambios que te sugiero:
• Desplazamiento automático del panel izquierdo a la sección activa actualmente en los documentos principales. Esto puede ser útil para llevar un registro de las secciones actuales, futuras y pasadas. • Copiar en el portapapeles: Algunos comandos pueden ser extensos y la función de copiar puede ser útil cuando se trabaja con este tipo de comandos. • Formato de contenido de archivos de documentos: Después de la migración, el formato del contenido de algunas páginas no es adecuado; p. ej., en la sección Resource Type (Tipo de recurso) de la descripción general de kubectl. Esto degrada la experiencia del usuario.
Estos son los cambios que pueden mejorar la experiencia del usuario en el sitio web de Kubernetes y también pueden aumentar su productividad.