Guia de estilo do tutorial

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: os tutoriais são apresentados em um painel lateral no lado direito do Console do Google Cloud.
  • Navegação: os usuários podem percorrer o tutorial usando os botões Próxima e Anterior em cada etapa. Eles também podem fechar o tutorial e continuar de onde pararam.
  • Código para Go: os snippets de código podem ser copiados diretamente para o Cloud Shell.

Sessão do console com o tutorial iniciado

Uma sessão do Editor do Cloud Shell com um painel de tutorial aberto. Os usuários podem copiar o código diretamente para o Cloud Shell. Basta clicar em um botão e alternar entre as páginas com os botões Próxima e Anterior.

Estilo de escrita

  • Fique claro: os tutoriais precisam ser informativos e úteis em termos de tom, mas não muito formal.
  • Você, o usuário: use pronomes da segunda pessoa do domínio (use: você, sua. Não use: nós. nosso e assim por diante)
  • Explique a causa e o efeito: ao solicitar que os usuários realizem uma etapa, explique o motivo por trás da ação e do resultado esperado.
  • Tenha objetivos focados: antes de escrever o conteúdo do seu tutorial, estabeleça uma meta bem definida que os usuários devem alcançar. Crie seu tutorial tendo em mente essa meta.
Original Revisado Melhoria
Na próxima página, você aprenderá a criar um novo tutorial. para a 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!

Este guia mostrará a você como criar seu próprio tutorial interativo. Ele também mostrará como gerar um botão que os usuários poderão usar para iniciar seu tutorial depois de concluído.

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 do painel de tutorial significam que os usuários acessam uma quantidade limitada de informações de cada 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 apresentação.

    • Defina as expectativas: explique resumidamente aos usuários as vantagens de concluir este tutorial.
    • Compromisso com o tempo estimado: faça uma estimativa aproximada de quanto tempo os usuários gastarão no tutorial. Crie um tutorial que possa ser concluído em 15 minutos. Se o tutorial for mais longo (ou tiver mais de 15 páginas densas), convém dividi-lo em uma série de tutoriais menores.
    • Seja direto: informe claramente aos usuários os recursos ou acessos que eles deverão configurar previamente, para que possam trabalhar no tutorial sem interrupções.
    Exemplo

    ## Vamos começar!

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

    Neste guia, você verá como criar seu próprio tutorial interativo (como este). Ele também mostrará como gerar um botão que os usuários poderão usar para iniciar seu tutorial depois de concluído.

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

    **Pré-requisitos**: uma Conta de faturamento do Cloud

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

  • Página de contexto:

    • Defina o cenário: sempre que for escrever um tutorial, é importante apresentar o 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.

    Siga para a próxima etapa e comece a configurar 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 em contexto

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

    O conteúdo é exibido junto com o ambiente do Cloud Shell, no qual você pode executar as etapas do tutorial. Com o tutorial e o ambiente de desenvolvimento abertos no mesmo local, fica mais fácil para os usuários começarem a usar seu projeto por meio de uma experiência simples em uma única tela.

    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ê escreverá e iniciará 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 material do tutorial oferecido como conteúdo estático. Isso dá aos usuários a liberdade de escolher como 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 um 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 à criação de tutoriais no Cloud Shell") alterando-o 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 o ícone de um troféu (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) para parabenizar os usuários que dedicaram tempo para finalizar o tutorial.
    • Conclusão: resuma as lições importantes que você gostaria que os usuários tirassem do tutorial.
    • Próximas etapas: ajude os usuários ao longo da jornada apresentando as próximas etapas – pode ser uma leitura recomendada, recursos complementares ou até mesmo outro tutorial.
    • Dê dicas úteis aos usuários: aconselhe-os a limpar os recursos de teste que criaram para o tutorial, a fim de evitar cobranças indesejadas.
    Exemplo

    ## Parabéns!

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

    Pronto!

    Agora os usuários podem iniciar seu tutorial no Cloud Shell e começar a usar seu projeto com facilidade.

    Para ver uma lista completa das ferramentas de criação de tutoriais do Cloud Shell, consulte a [Referência do Markdown para tutoriais] (https://cloud.google.com/shell/docs/tutorial-markdown-reference) – em inglês.

    **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>`.