Esta página contiene 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)
- Escritor 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 motivo de este proyecto sería mejorar la hoja de referencia y los documentos de referencia de kubectl existentes.
Estos son los objetivos principales de este proyecto: • Crear más y mejores ejemplos de kubectl • Agregar ejemplos de kubectl a la hoja de referencia de kubectl • Refactoriza los documentos de kubectl para obtener la máxima utilidad.
Objetivo I: Ejemplos para kubectl:
Trabajaremos en estrecha colaboración con los grupos de interés especiales de la CLI para conocer el contexto, el tipo de ejemplos que más desean los usuarios de Kubernetes y documentarlo. Esto puede variar desde mejorar los comandos de kubectl existentes en la hoja de referencia hasta agregar comandos nuevos a la hoja de referencia.
Objetivo II: Mejorar la utilidad de los documentos:
Para aumentar la utilidad de los documentos, puedes hacer lo siguiente:
• Eliminar las dificultades de los principiantes • Reorganizar el comando de kubectl en cierto orden para garantizar la continuidad en el flujo lógico
Elimina las dificultades de los principiantes con mejores explicaciones sobre comandos y casos de usuario. Esto puede parecer simple, pero puede influir significativamente 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 Node.js. Después de unas horas, quería reducirlo, así que intenté borrar el Pod, pero, debido a la naturaleza de autorreparación, se volvieron a crear. Estaba desconcertado con lo que estaba pasando y me preguntaba por qué se recreaba en lugar de borrarse. Después de algunas búsquedas en la Web, comprobé que borrar Pods no es lo mismo que borrar una implementación. Para un ojo capacitado, esto podría parecer simple, pero una explicación clara que elimine este tipo de ambigüedades es lo que distingue a un buen documento de un gran documento.
Reordenar el comando de kubectl en cierto orden para garantizar la continuidad en el flujo lógico Si eres alguien como yo que cree firmemente en la narración, probablemente te preguntarás, ¿cómo puedes incorporar los elementos de narración en una hoja de documento que tiene una lista de comandos terminales, digo, que se puede hacer? Todo lo que aprendemos siempre tiene un flujo lógico: un punto de partida y un punto de finalización, si se quiere. Kubectl como herramienta de línea de comandos obviamente tiene una curva de aprendizaje, de hecho, coincide con la de Kubernetes. Dado que casi todos comienzan su recorrido con Kubernetes a través de kubectl (excepto las personas que usan IU web) y como la curva de aprendizaje está estrechamente vinculada a la curva de aprendizaje de Kubernetes, los documentos pueden mejorar significativamente con solo cambiar el orden de estos comandos y, luego, incorporar elementos de narración. Por ejemplo, las funciones como el ajuste de escala automático horizontal de Pods se pueden explicar después de explicar los recursos con ilustraciones y ejemplos reales.
Objetivo III: Mejoras en la usabilidad de Documentos:
La migración reciente del sitio web de Kubernetes a Docsy Hugo es increíble y supone un cambio masivo en la perspectiva de los documentos. Si bien la migración se realizó con éxito, todavía hay margen para muchas mejoras en el espacio de documentos.
Yo sugeriría algunos cambios.
• El panel izquierdo se desplaza automáticamente a la sección actualmente activa de los documentos principales. Esta opción puede ser útil para hacer un seguimiento de las secciones actuales, próximas y pasadas. • Copiar en el portapapeles: Algunos comandos pueden tardar mucho tiempo y la función de copiar puede resultar útil cuando trabajas con este tipo de comandos. • Formato de contenido de los archivos de documentos: Después de la migración, el contenido de algunas páginas no tiene el formato adecuado, p. ej., la sección Tipo de recurso en el resumen 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, además, aumentar la productividad de los usuarios.