Los siguientes lineamientos te ayudarán a presentar tu contenido en forma de instructivo para que los usuarios puedan familiarizarse de manera efectiva con tu proyecto.
Características de Cloud Shell
- Diseño exclusivo: Los instructivos se presentan en un panel lateral en el lado derecho de la consola de Google Cloud.
- Navegación: Los usuarios pueden desplazarse por el instructivo con los botones Siguiente y Anterior en cada paso. También pueden cerrar el instructivo y reanudarlo desde donde lo dejaron.
- Código listo para usar: Los fragmentos de código se pueden copiar directamente en Cloud Shell.
Sesión del editor de Cloud Shell con un panel de instructivo abierto. Los usuarios pueden hacer clic en un botón para copiar el código directamente en Cloud Shell y pueden desplazarse entre las páginas con los botones Siguiente y Anterior.
Estilo de escritura
- Usa lenguaje simple: Los instructivos deben tener un tono informativo y útil sin ser demasiado formales.
- Tú, el usuario: Usa pronombres de la segunda persona singular (usa: tú, tu; no uses: nosotros, yo, nuestro, etcétera).
- Explica la causa y el efecto: Cuando pidas a los usuarios que sigan un paso, debes explicar el razonamiento detrás de la acción y los resultados esperados.
- Enfoca tus objetivos: Antes de escribir el contenido de tu instructivo, establece, de forma bien definida, el objetivo que deseas que logren tus usuarios. Crea tu instructivo con este objetivo en mente.
| Original | Revisado | Mejora |
| En la página siguiente, aprenderás cómo crear un instructivo nuevo. | Continúa con el paso siguiente para comenzar a configurar tu instructivo. | Se mantiene el enfoque en el usuario, se usa voz activa.
Uso de lenguaje relajado |
| Ejecuta este comando: ```gcloud projects list --format="table[box,title=Projects](name, projectId)"``` |
Ejecuta el siguiente comando, a fin de mostrar una lista tabulada de todos tus proyectos y sus números de ID, titulada “Proyectos”: ```gcloud projects list --format="table[box,title=Projects](name, projectId)"``` | Se explica del razonamiento por adelantado, a fin de fijar las expectativas sobre el resultado |
Let's get started!
|
Let's get started!
En esta guía podrás ver cómo crear tu propio instructivo interactivo. Además, se te indicarán los pasos para generar un botón que los usuarios puedan utilizar a fin de dar inicio a tu instructivo finalizado. |
Hoja de ruta clara con las lecciones que se tratan en el instructivo
Asegúrate de mantener este enfoque cuando escribas contenido. |
Prácticas recomendadas
Trata de ser breve: Las restricciones de espacio exclusivas del panel de este instructivo implican que solo se puede presentar una cantidad limitada de información por usuario. Evita insertar párrafos grandes que sean difíciles de escanear y que requieran de desplazamiento vertical; trata de favorecer la información presentada en párrafos pequeños.
Trata de no insertar más de 5 pasos y 3 fragmentos de código por página.
Idealmente, los párrafos deben ser de 5 líneas o menos, y deben tratar conceptos singulares.
Si es necesario que una página sea larga, trata de que tenga, como máximo, el doble de la longitud del panel.
El código y los bloques de conectores deben ser lo suficientemente pequeños para ser leídos:
- Trata de escribir 10 líneas o menos.
- Trata de escribir un máximo de 80 caracteres por línea a fin de evitar el desplazamiento horizontal.
- Evita los bloques de código con varios comandos, a fin de evitar que los usuarios deban realizar una copia masiva.
Página introductoria: Inicia tu instructivo con una introducción.
- Establece expectativas: Explica, en forma breve, cómo tus usuarios se beneficiarán si completan tu instructivo.
- Establece un tiempo estimado: Estima a grandes rasgos cuánto tiempo pueden tardar tus usuarios en completar tu instructivo. Intenta crear un instructivo que se pueda finalizar en menos de 15 minutos. Si tu instructivo es más extenso o es de más de 15 páginas escritas por completo, considera dividirlo en una serie de instructivos más pequeños.
- Sé directo: Establece claramente cualquier recurso o acceso que sea un requisito previo necesario para los usuarios a fin de que trabajen en el instructivo sin interrupciones.
Ejemplo ## ¡Comencemos!
Haz que tus usuarios comiencen a trabajar rápidamente en tu proyecto con la incorporación de un instructivo interactivo.
Esta guía te mostrará cómo crear tu propio instructivo interactivo (como este). Además, se te indicarán los pasos para generar un botón que los usuarios puedan utilizar a fin de dar inicio a tu instructivo finalizado.
**Tiempo para completar**: Alrededor de 10 minutos
**Requisitos previos**: Tener una cuenta de Facturación de Cloud
Haz clic en el botón **Continuar** para avanzar al paso siguiente.
Página en segundo plano
- Prepara el escenario: Cuando escribes un instructivo, suele ser útil proporcionar contexto. Esto puede significar proporcionar una descripción general breve de los productos o repasar de forma rápida las características destacadas de una IU.
Ejemplo ## ¿Qué es Cloud Shell?
Antes de comenzar, repasemos brevemente lo que Cloud Shell puede hacer.
Cloud Shell es una máquina virtual alojada y personal precargada con herramientas para desarrolladores de productos de Google Cloud. Este entorno interactivo de shell incluye un editor de códigos integrado, almacenamiento en un disco persistente y funcionalidad de vista previa web. Para usar solo el acceso a la línea de comandos, visita [console.cloud.google.com/cloudshell] https://console.cloud.google.com/cloudshell).
Puedes dirigir a tus usuarios a Cloud Shell, a fin de ayudarlos a comenzar rápidamente con tu proyecto; lo que les brinda la oportunidad de revisar casos prácticos y familiarizarse con la funcionalidad de tu proyecto.
Continua con el paso siguiente para comenzar a configurar tu instructivo.
Ejemplos básicos:
- Hello World: El primer ejemplo que proporciones debe ser lo suficientemente simple como para que tu usuario pueda hacer pruebas sin necesitar muchas explicaciones. Debe ser tu equivalente de Hello World. Usa esto como base para ejemplificar los conceptos en el instructivo.
Ejemplo ## Instructivos en contexto
Lo que observas en este momento es un instructivo en contexto.
El contenido se muestra junto con el entorno de Cloud Shell, en el que puedes realizar los pasos del instructivo. Mantener abiertos el instructivo y el entorno de desarrollo en el mismo lugar, facilita que tus usuarios puedan comenzar a usar tu proyecto a través de una experiencia de pantalla única, sin complicaciones.
Intenta ejecutar un comando ahora:
```Bash
eco "Hola Cloud Shell"
```
**Sugerencia**: Haz clic en el botón de copiar que está al costado del cuadro de códigos, a fin de pegar el comando para ejecutarlo en la terminal de Cloud Shell.
A continuación, podrás iniciar y escribir instructivos básicos.
Contenido del instructivo
- Da formato con precaución: El formato del texto (negrita, cursiva, etc.) es una distracción; úsalo solo cuando sea necesario y provechoso (para advertencias, aprendizaje de claves, entre otros).
- Usa gramática coherente: Usa el modo imperativo al momento de describir acciones de los usuarios y asegúrate de terminar las oraciones con un punto.
- Menciona los vínculos: Incluye vínculos complementarios ([texto del vínculo][URL del vínculo]) cuando sea esencial para el contexto, a fin de que tus usuarios puedan realizar su propia investigación.
- Elige la función de destacar en lugar de las capturas de pantalla: La función de destacar, una acción que destaca dónde se encuentran los elementos de la IU en la consola de Google Cloud, demuestra la posición para que los usuarios puedan identificar los elementos sin buscar una imagen.
- Vista alternativa: Si es posible, proporciona un vínculo al contenido de tu instructivo, como contenido estático. Esto permite que los usuarios tengan la libertad de elegir cómo desean recibir la información que se entrega.
- Se agradecen las sugerencias: Cuando corresponda, agrega sugerencias (destacadas como "**Sugerencias:**"), a fin de proporcionar soluciones intuitivas y recomendaciones para los usuarios.
Ejemplo ## Escritura en Markdown
Para escribir tu instructivo, usa [Markdown](https://en.wikipedia.org/wiki/Markdown) y sigue estos lineamientos:
### Edita el título
Modifica el título de este instructivo (“# Introducción a la escritura de instructivos en Cloud Shell”), cambiándolo a lo siguiente:
```
# Enséñame a escribir un instructivo
```
### Agrega un paso nuevo
A continuación, agrega un paso después del título, como el que se ve a continuación:
```
## Paso 1
Este es un nuevo paso que agregué.
```
Cada “paso” de un instructivo se muestra en una página.
**Sugerencia**: Los usuarios pueden usar los botones “Atrás” y “Continuar/Adelante”, a fin de desplazarse entre los pasos.
Resumen
- Felicitaciones: Asegúrate de agregar un ícono de trofeo (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>), para agradecer a los usuarios por tomarse el tiempo de finalizar el instructivo.
- Conclusión: Resume las lecciones importantes que te gustaría que tus usuarios saquen en limpio del instructivo.
- Próximos pasos: Ayuda a los usuarios en su recorrido, entregándoles los pasos siguientes; estos pueden ser lecturas recomendadas, recursos complementarios o, incluso, otro instructivo.
- Cuida a tus usuarios: Debes aconsejarles que eliminen todos los recursos de prueba que hayan creado en el instructivo, a fin de evitar cargos de facturación no deseados.
Ejemplo ## Felicitaciones
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
Listo.
Ya puedes hacer que tus usuarios inicien tu instructivo en Cloud Shell y que usen tu proyecto con facilidad.
Para ver una lista completa de las herramientas de escritura de instructivos en Cloud Shell, consulta [Tutorial Markdown Reference] https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**No olvides limpiar después de usar**: Si creaste proyectos de prueba, asegúrate de borrarlos, a fin de evitar cargos innecesarios. Usa `gcloud projects delete <PROJECT-ID>`.