Guía de escritura de explicaciones

Para que los usuarios se familiaricen efectivamente con su proyecto, aquí hay algunas pautas para ayudarlo a presentar mejor su contenido en forma de explicación.

Características de Cloud Shell

  • Diseño exclusivo: Las explicaciones se presentan en un panel lateral (310 píxeles) en el lado derecho de Google Cloud Console.
  • Navegación: Los usuarios pueden moverse a través de la explicación usando los botones “Continuar” y “Atrás”. Ten en cuenta que, para avanzar en un paso visitado previamente, el botón dirá “Adelante”, en lugar de “Continuar”. Los usuarios también tienen la opción de salir de la explicación con “Cancelar tutorial” y luego pueden reanudar desde donde lo dejaron.
  • Código listo para usar: Puedes incluir fragmentos de código en tu explicación. Estarán formateados dentro del código con el ícono Ícono copiar, a fin de permitir que los usuarios peguen estos fragmentos directamente en Cloud Shell.

Sesión de consola con explicación lanzada

Sesión de consola con el panel explicación abierto en el lado derecho. Los usuarios pueden copiar el código directamente en Cloud Shell con el ícono intercalado y pueden desplazarse entre las páginas con los botones “Atrás” y “Continuar”.

Estilo de escritura

  • Usa lenguaje simple: Las explicaciones 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 explicación, establece, de forma bien definida, el objetivo que deseas que logren tus usuarios. Crea tu explicación con este objetivo en mente.
Original Revisado Mejora
En la página siguiente, aprenderá a crear una nueva explicación. Continúa con el paso siguiente para comenzar a configurar tu explicación. 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!

Esta guía le mostrará cómo crear su propia explicación interactiva. También lo guiará a través de la generación de un botón que los usuarios pueden usar para iniciar su explicación terminada.

Hoja de ruta clara con las lecciones que se tratan en la explicación

Asegúrate de mantener este enfoque cuando escribas contenido.

Recomendaciones

  • Trata de ser breve: Las restricciones de espacio exclusivas del panel de esta explicación 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 explicación con una introducción.

    • Establece expectativas: Explica, en forma breve, cómo tus usuarios se beneficiarán si completan tu explicación.
    • Establece un tiempo estimado: Estima a grandes rasgos cuánto tiempo pueden tardar tus usuarios en completar tu explicación. Intenta crear una explicación que se pueda terminar en menos de 15 minutos. Si tu explicación es más extensa o es de más de 15 páginas escritas por completo, considera dividirla en una serie de explicaciones más pequeñas.
    • Sé directo: Establece claramente cualquier recurso o acceso que sea un requisito previo necesario para los usuarios a fin de que trabajen en la explicación sin interrupciones.
    Ejemplo

    ## ¡Comencemos!

    Haz que tus usuarios comiencen a trabajar rápidamente en tu proyecto con la incorporación de una explicación interactiva.

    Esta guía le mostrará cómo crear su propia explicación interactiva (como esta). También lo guiará a través de la generación de un botón que los usuarios pueden usar para iniciar su explicación terminada.

    **Tiempo para completar**: Alrededor de 10 minutos

    **Requisitos previos**: Tener una cuenta de GCP

    Haz clic en el botón **Continuar** para avanzar al paso siguiente.

  • Página en segundo plano

    • Establezca la escena: A menudo es útil, al escribir una explicación, proporcionarle 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 explicación.

  • 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 la explicación.
    Ejemplo

    ## Explicaciones en contexto

    Lo que estás viendo ahora es una explicación en contexto.

    El contenido se muestra junto con el entorno de Cloud Shell, donde puede llevar a cabo los pasos de la explicación. Tener la explicación y el entorno de desarrollo abiertos en el mismo lugar hace que sea más fácil para sus usuarios comenzar a usar su proyecto a través de una experiencia sencilla de pantalla única.

    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, escribirá y lanzará una explicación básica.

  • Contenido de la explicación

    • 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.
    • Prefiere destacar en vez de usar capturas de pantalla: “Destacar”, una acción que destaca dónde se encuentran los elementos de IU en Console, demuestra su posición a fin de que los usuarios puedan identificarlos sin tener que buscar una imagen.
    • Vista alternativa: Si es posible, proporciona un vínculo al contenido de tu explicación, 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 su explicación, use [Markdown](https://en.wikipedia.org/wiki/Markdown) y siga estas pautas:

    ### Edita el título

    Modifique el título de esta explicación ('# Introducción a la escritura de explicaciones en Cloud Shell') cambiándolo a:

    ```

    # Enséñame a escribir una explicación

    ```

    ### 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 una explicación 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úrese de agregar un ícono de trofeo (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) para apreciar a los usuarios que se toman el tiempo para terminar la explicación.
    • Resumen: Resuma las lecciones importantes que le gustaría que los usuarios aprendieran de la explicación.
    • Próximos pasos: Ayuda a los usuarios en su recorrido, entregándoles los pasos siguientes; estos pueden ser lecturas recomendadas, recursos complementarios o, incluso, otra explicación.
    • Cuida a tus usuarios: Debes aconsejarles que eliminen todos los recursos de prueba que hayan creado en la explicación, a fin de evitar cargos de facturación no deseados.
    Ejemplo

    ## Felicitaciones

    <walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>

    Listo.

    Ahora puede hacer que los usuarios inicien su explicación en Cloud Shell y que comiencen a usar su proyecto con facilidad.

    Para obtener una lista completa de las herramientas de escritura de explicaciones de Cloud Shell, consulte la [Referencia de Markdown de explicaciones](https://cloud.google.com/shell/docs/walkthrough-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>`.