Las siguientes directrices te ayudarán a presentar tu contenido en formato de tutorial para que tus usuarios puedan familiarizarse con tu proyecto de forma eficaz.
Características de Cloud Shell
- Diseño único: los tutoriales se muestran en un panel lateral situado en la parte derecha de la consola Google Cloud .
- Navegación: los usuarios pueden desplazarse por el tutorial con los botones Siguiente y Anterior de cada paso. También pueden cerrar el tutorial y continuar donde lo dejaron.
- Código para llevar: los fragmentos de código se pueden copiar directamente en Cloud Shell.
Una sesión del editor de Cloud Shell con un panel de tutorial abierto. Los usuarios pueden copiar código directamente en Cloud Shell haciendo clic en un botón y pueden desplazarse entre páginas con los botones Siguiente y Anterior.
Estilo de escritura
- Mantén un tono ligero: los tutoriales deben ser informativos y útiles, pero no demasiado formales.
- Tú, el usuario: usa pronombres de segunda persona (sí: tú, tu; no: nosotros, yo, nuestro, etc.).
- Explica la causa y el efecto: cuando pidas a los usuarios que lleven a cabo un paso, explica el motivo de la acción y el resultado esperado.
- Define objetivos concretos: antes de escribir el contenido del tutorial, establece un objetivo bien definido que quieras que alcancen tus usuarios. Crea tu tutorial teniendo en cuenta este objetivo.
| Original | Revisado | Mejora |
| En la página siguiente, aprenderá a crear un tutorial. | Continúa con el siguiente paso para empezar a configurar el tutorial. | Centrarse en el usuario y usar la voz activa
Uso de lenguaje informal |
| Ejecuta este comando:
``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
Para mostrar una lista tabulada de todos tus proyectos y sus números de ID, titulada "Projects" (Proyectos), ejecuta el siguiente comando: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` | Explicación del razonamiento inicial para definir las expectativas sobre el resultado |
Let's get started!
|
Let's get started!
En esta guía se explica cómo crear tu propio tutorial interactivo. También te guiará para generar un botón que los usuarios puedan usar para iniciar el tutorial terminado. |
Hoja de ruta clara de las lecciones que se tratan en el tutorial
No olvides centrarte en esto cuando escribas contenido. |
Prácticas recomendadas
Sé breve: las limitaciones de espacio del panel del tutorial implican que solo se puede mostrar una cantidad limitada de información a un usuario a la vez. Evita los bloques de texto grandes que sean difíciles de leer y que requieran desplazarse verticalmente. En su lugar, presenta la información en fragmentos breves.
Procura que no haya más de 5 pasos y 3 fragmentos de código por página.
Lo ideal es que los párrafos tengan cinco líneas o menos y que traten un solo concepto.
Si una página debe ser larga, procura que tenga como máximo el doble de la longitud del panel.
El código y los bloques de terminal deben ser lo suficientemente pequeños para que se puedan leer:
- Intenta que tenga 10 líneas o menos.
- Intenta que cada línea tenga 80 caracteres como máximo para reducir el desplazamiento horizontal.
- Evita los bloques de código de varios comandos para que los usuarios no tengan que hacer una copia y ejecución masivas.
Página de introducción: empieza el tutorial con una introducción.
- Define las expectativas: explica brevemente cómo se beneficiarán los usuarios al completar este tutorial.
- Tiempo estimado: calcula aproximadamente cuánto tiempo pueden dedicar los usuarios al tutorial. Intenta crear un tutorial que se pueda completar en menos de 15 minutos. Si tu tutorial es más largo (o consta de más de 15 páginas con mucho texto), plantéate dividirlo en una serie de tutoriales más pequeños.
- Sé sincero: indica claramente los recursos o el acceso que los usuarios deben tener configurados para completar el tutorial sin interrupciones.
Ejemplo ## ¡Empecemos!
Prepara rápidamente a los usuarios para que puedan usar tu proyecto incluyendo un tutorial interactivo.
En esta guía se explica cómo crear tu propio tutorial interactivo (como este). También te guiará para generar un botón que los usuarios puedan usar para iniciar el tutorial terminado.
**Duración aproximada:** alrededor de 10 minutos.
**Requisitos**: una cuenta de facturación de Cloud
Haz clic en el botón **Continuar** para ir al siguiente paso.
Página en segundo plano
- Describe la situación: cuando escribas un tutorial, a menudo te resultará útil proporcionar contexto. Esto puede significar ofrecer una breve descripción general del producto o repasar rápidamente las funciones destacadas de una interfaz de usuario.
Ejemplo ## ¿Qué es Cloud Shell?
Antes de empezar, vamos a repasar brevemente lo que puede hacer Cloud Shell.
Cloud Shell es una máquina virtual personal alojada que viene precargada con herramientas para desarrolladores de productos de Google Cloud . Este entorno de shell interactivo incluye un editor de código integrado, almacenamiento en disco persistente y una función de vista previa web. Para usar solo el acceso mediante línea de comandos, visita [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).
Puedes dirigir a tus usuarios a Cloud Shell para ayudarles a empezar rápidamente con tu proyecto, lo que les dará la oportunidad de completar un caso práctico y familiarizarse con las funciones de tu proyecto.
Avanza al paso siguiente para empezar a configurar tu propio tutorial.
Ejemplos básicos:
- Hola, mundo: el primer ejemplo que proporciones debe ser lo suficientemente sencillo para que el usuario pueda probarlo sin necesidad de muchas explicaciones. Debería ser el equivalente a "Hello World". Usa este ejemplo como base para seguir desarrollando conceptos a lo largo del tutorial.
Ejemplo ## Tutoriales en contexto
Lo que estás viendo ahora es un tutorial en contexto.
El contenido se muestra junto con el entorno de Cloud Shell, donde puedes seguir los pasos del tutorial. Tener el tutorial y el entorno de desarrollo abiertos en el mismo lugar facilita a los usuarios empezar a usar tu proyecto a través de una experiencia sencilla en una sola pantalla.
Ejecuta un comando:
```bash
echo "Hello Cloud Shell"
```
**Nota:** Haz clic en el botón de copiar situado en el lateral del cuadro de código para pegar el comando en la terminal de Cloud Shell y ejecutarlo.
A continuación, escribirás y publicarás un tutorial básico.
Contenido del tutorial
- Aplica formatos con precaución: los formatos de texto (negrita, cursiva, etc.) distraen. Úsalos solo cuando sea necesario y para tu beneficio (por ejemplo, en advertencias o puntos clave).
- Gramática coherente: usa el imperativo al describir las acciones de los usuarios y asegúrate de terminar las frases con un punto.
- Referencias a enlaces: cuando sea esencial para el contexto, incluye enlaces complementarios ([texto del enlace](URL del enlace)) para que los usuarios puedan hacer sus propias investigaciones.
- Elige la opción de destacar en lugar de hacer capturas de pantalla: esta opción resalta la ubicación de los elementos de la interfaz de usuario en la Google Cloud consola Google Cloud , lo que permite a los usuarios identificar los elementos sin tener que buscar una imagen.
- Vista alternativa: si es posible, proporciona un enlace al contenido del tutorial como contenido estático. De esta forma, los usuarios podrán elegir cómo quieren consumir la información proporcionada.
- Consejos: cuando sea pertinente, añade consejos (indicados con "**Consejo:**") para ofrecer a los usuarios soluciones más intuitivas y prácticas recomendadas.
Ejemplo ## Escribir en Markdown
Para escribir tu tutorial, usa [Markdown](https://en.wikipedia.org/wiki/Markdown) y sigue estas directrices:
### Editar el título
Modifica el título de este tutorial ('# Introduction to writing tutorials in Cloud Shell') y cámbialo por el siguiente:
```
# Enséñame a escribir un tutorial
```
### Añadir un paso
Incluye un paso justo después del título tal y como se indica a continuación:
```
## Paso 1
Este es un nuevo paso que acabo de añadir.
```
Cada paso de un tutorial aparece en una página.
**Nota:** Para desplazarse por los pasos, los usuarios usarán los botones "Atrás" y "Continuar/Adelante".
Resumen
- Enhorabuena: añade un icono de trofeo (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) para agradecer a los usuarios que se hayan tomado su tiempo para completar el tutorial.
- Resumen: resume los aspectos importantes que quieres que los usuarios se lleven del tutorial.
- Próximos pasos: ayuda a los usuarios en su recorrido proporcionándoles los siguientes pasos, que pueden ser lecturas recomendadas, recursos complementarios u otro tutorial.
- Protege a tus usuarios: recomiéndales que eliminen los recursos de prueba que hayan creado para seguir el tutorial y así evitar cargos no deseados.
Ejemplo ## ¡Enhorabuena!
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
¡Listo!
Ahora, los usuarios pueden iniciar tu tutorial en Cloud Shell y empezar a usar tu proyecto fácilmente.
Para ver una lista completa de las herramientas para escribir tutoriales de Cloud Shell, consulta la [referencia de Markdown de tutoriales](https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**No olvides limpiar**: si has creado proyectos de prueba, asegúrate de eliminarlos para evitar que se te cobren cargos innecesarios. Usa `gcloud projects delete <PROJECT-ID>`.