Guia de instruções de escrita

Para que os usuários se familiarizem de maneira eficaz com seu projeto, aqui estão algumas diretrizes para ajudar a apresentar melhor seu conteúdo em forma de tutorial.

Recursos do Cloud Shell

  • Layout exclusivo: as instruções são apresentadas em um painel lateral (310 pixels de largura) no lado direito do Console do Google Cloud.
  • Navegação: os usuários podem percorrer o tutorial usando os botões "Continuar" e "Voltar". Para avançar por um passo anteriormente visto, o botão é "Avançar", em vez de "Continuar". Os usuários também têm a opção de sair do tutorial com "Cancelar tutorial" e, posteriormente, podem retomar de onde pararam.
  • Código "para viagem": você pode incluir trechos de código no seu tutorial. Eles serão codificados com este ícone inline, Ícone de cópia, para permitir que os usuários colem esses snippets no Cloud Shell diretamente.

Sessão do console com o tutorial lançado

Sessão do console com o painel do tutorial aberto no lado direito. Os usuários podem copiar o código diretamente no Cloud Shell usando o ícone inline , além de se mover entre as páginas usando "Voltar" e "Continuar".

Estilo de escrita

  • Seja claro: os tutoriais precisam ser informativos e úteis, mas não excessivamente formais.
  • Você, o usuário: use pronomes da segunda pessoa do singular (use: você, seu. Não use: nós, eu, nosso etc.).
  • Explique causa e efeito: ao pedir que os usuários realizem uma etapa, explique o raciocínio por trás da ação e o resultado esperado.
  • Tenha objetivos focados: antes de escrever o conteúdo do seu tutorial, estabeleça um objetivo bem definido que você quer que seus usuários cumpram. Crie o tutorial mantendo esse objetivo em mente.
Original Revisado Melhoria
Na próxima página, você aprenderá como criar um novo tutorial. Continue na próxima etapa para começar a configurar seu tutorial. O foco é no usuário; uso de voz ativa.

Uso de linguagem descontraída.

Execute este comando:

``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ```

Para exibir uma lista tabulada de todos os projetos e os números de identificação respectivos, intitulados "Projetos", execute o comando a seguir: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` Explicação do raciocínio inicial para definir expectativas sobre o resultado.
Let's get started! Let's get started!

Neste guia, você verá como criar seu próprio tutorial interativo. Ele também explica como gerar um botão que os usuários podem usar para iniciar seu tutorial finalizado.

Roteiro claro das lições abordadas no tutorial.

Mantenha esse foco ao escrever seu conteúdo!

Práticas recomendadas

  • Seja breve: as restrições de espaço exclusivas do painel do tutorial significam que uma quantidade limitada de informações pode ser apresentada ao usuário por vez. Evite grandes blocos de texto que são difíceis de analisar e exigem rolagem vertical. Favoreça informações apresentadas em pequenos blocos.

    • Tenha como meta cinco etapas, no máximo, e três snippets de código por página.

    • Os parágrafos precisam, idealmente, ser de cinco linhas ou menos, e devem lidar com um único conceito.

    • Se precisa de uma página longa, procure que ela tenha, no máximo, duas vezes o comprimento do painel.

    • Os blocos de código e do terminal precisam ser pequenos o suficiente para permitir a leitura:

      • Use, no máximo, 10 linhas.
      • Use, no máximo, 80 caracteres por linha, para reduzir a rolagem horizontal.
      • Evite blocos de código com vários comandos para que os usuários não tenham que executar uma cópia em massa.
  • Página introdutória: inicie o tutorial com uma introdução.

    • Defina expectativas: explique brevemente como os usuários serão beneficiados com o tutorial.
    • Compromisso de tempo estimado: estime aproximadamente quanto tempo os usuários podem esperar gastar no tutorial. Procure criar um tutorial que possa ser concluído em menos de 15 minutos. Se o tutorial for mais longo (ou tiver mais de 15 páginas com palavras densas), considere dividi-lo em uma série de tutoriais menores.
    • Seja franco: indique claramente os requisitos de recursos ou acessos que os usuários possam precisar para trabalhar com o tutorial sem interrupções.
    Exemplo

    ## Vamos começar!

    Permita que os usuários comecem a usar rapidamente seu projeto incluindo um tutorial interativo.

    Este guia mostra como criar seu próprio tutorial interativo (como este). Ele também indica como criar um botão que os usuários podem usar para iniciar seu tutorial finalizado.

    **Tempo para conclusão**: cerca de 10 minutos

    **Pré-requisitos**: conta do GCP

    Clique no botão **Continuar** para avançar à próxima etapa.

  • Página de contexto:

    • Prepare o terreno: muitas vezes é útil, ao escrever um tutorial, fornecê-lo com contexto. Pode ser uma breve visão geral do produto ou a execução rápida dos recursos principais de uma interface do usuário.
    Exemplo

    ## O que é o Cloud Shell?

    Antes de começar, vamos resumir o que o Cloud Shell pode fazer.

    O Cloud Shell é uma máquina virtual pessoal hospedada que vem pré-carregada com ferramentas de desenvolvedor para produtos do Google Cloud. Esse ambiente de shell interativo vem com um editor de código integrado, armazenamento em disco permanente e funcionalidade de visualização da Web. Para usar somente o acesso de linha de comando, acesse [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).

    Você pode direcionar os usuários ao Cloud Shell para ajudá-los a começar rapidamente um projeto, o que dá a eles a oportunidade de ver um caso de uso e se familiarizar com a funcionalidade do seu projeto.

    Continue na próxima etapa para começar a configurar o seu tutorial.

  • Exemplos básicos:

    • Hello World: o primeiro exemplo que você apresenta deve ser simples o bastante para que os usuários testem sem muita explicação. Deve ser o equivalente do Hello World. Use este exemplo como base para continuar criando exemplos de conceitos por meio do tutorial.
    Exemplo

    ## Tutoriais no contexto

    O que você está vendo agora é um tutorial no contexto.

    O conteúdo é mostrado junto com o ambiente do Cloud Shell, onde você pode executar as etapas do tutorial. Ter o tutorial e o ambiente de desenvolvimento abertos no mesmo local facilita para os usuários começarem a usar seu projeto com uma experiência direta de tela única.

    Tente executar um comando agora:

    ```bash

    echo "Hello Cloud Shell"

    ```

    **Dica**: clique no botão "Copiar" na lateral da caixa de código para colar o comando no terminal do Cloud Shell e executá-lo.

    Em seguida, você vai escrever e lançar um tutorial básico.

  • Conteúdo do tutorial

    • Formate com cuidado: a formatação do texto (negrito, itálico etc.) é uma distração; use apenas quando necessário e a seu favor (para avisos, pontos de aprendizado importantes etc.).
    • Gramática consistente: use imperativo para descrever a ação do usuário e termine frases com ponto final.
    • Faça referências a links: onde for essencial para o contexto, inclua links complementares ([texto do link] (URL do link)) para que os usuários possam fazer a própria pesquisa.
    • Use destaques em vez de capturas de tela: destaque onde os elementos da interface do usuário estão no console, demonstrando a posição deles para que os usuários possam identificar elementos sem ter que procurar em uma imagem.
    • Visualização alternativa: se possível, forneça um link para o conteúdo do tutorial oferecido como conteúdo estático; isso dá aos usuários a liberdade de escolher como eles gostariam de consumir as informações fornecidas.
    • Dicas: quando aplicável, inclua dicas (use a chamada "**Dica:**") para fornecer aos usuários soluções mais intuitivas e práticas recomendadas.
    Exemplo

    ## Como escrever em Markdown

    Para escrever seu tutorial, use [Markdown](https://en.wikipedia.org/wiki/Markdown) e siga estas diretrizes:

    ### Edite o título

    Modifique o título deste tutorial ("# Introdução à redação de tutoriais no Cloud Shell") para:

    ```

    # Como escrever um tutorial

    ```

    ### Adicione uma nova etapa

    Em seguida, adicione uma etapa logo após o título, desta forma:

    ```

    ## Etapa 1

    Esta é uma nova etapa que acabei de adicionar.

    ```

    Cada "etapa" de um tutorial é exibida em uma página.

    **Dica**: para avançar pelas etapas, os usuários usarão os botões "Voltar" e "Continuar/Avançar".

  • Resumo

    • Parabéns: adicione um ícone de troféu (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) para reconhecer os usuários que dedicaram tempo para finalizar o tutorial.
    • Conclusão: resuma lições importantes que você gostaria que os usuários retirassem do tutorial.
    • Próximas etapas: ajude os usuários ao longo da jornada apresentando as próximas etapas, que podem ser leituras recomendadas, recursos adicionais ou até mesmo outro tutorial.
    • Cuide dos seus usuários: aconselhe-os a remover todos os recursos de teste que eles criaram para o tutorial, a fim de evitar cobranças indesejadas.
    Exemplo

    ## Parabéns!

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

    Pronto!

    Agora você pode fazer com que os usuários iniciem seu tutorial no Cloud Shell e comecem a usar seu projeto com facilidade.

    Para uma lista completa das ferramentas de escrita de tutoriais do Cloud Shell, consulte a [Referência de Markdown para tutoriais](https://cloud.google.com/shell/docs/walkthrough-markdown-reference).

    **Não se esqueça de limpar os recursos depois do uso**: se você criou projetos de teste, exclua todos eles para evitar cobranças desnecessárias. Use `gcloud projects delete <PROJECT-ID>`.