As diretrizes a seguir ajudarão você a apresentar seu conteúdo em formato de tutorial para que os usuários possam se familiarizar efetivamente com seu projeto.
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. Elas também podem fechar o tutorial e retomar de onde pararam.
- Código: os snippets de código podem ser copiados diretamente para o Cloud Shell.
Uma sessão do Editor do Cloud Shell com um painel de tutorial aberto. Os usuários podem copiar código diretamente para o Cloud Shell clicando em um botão e alternar entre as páginas com os botões Próxima e Anterior.
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 (use: você, seu. Não use: nós, eu, nossa e assim por diante)
- 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 claros: antes de escrever o conteúdo do seu tutorial, estabeleça uma meta bem definida que você quer que seus usuários atinjam. Crie seu tutorial tendo esse objetivo em mente.
| Original | Revisado | Melhoria |
| Na próxima página, você aprenderá a criar um novo tutorial. | Vá 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).
É possível direcionar os usuários ao Cloud Shell para ajudá-los a começar rapidamente seu projeto, oferecendo a oportunidade de percorrer um caso de uso e se familiarizar com a funcionalidade do 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.
- Escolha o destaque em vez das capturas de tela:o destaque, uma ação que destaca onde os elementos da UI estão no console do Google Cloud, demonstra a posição para que os usuários possam identificar elementos sem pesquisar 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 o tutorial, use o [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 o projeto com facilidade.
Para conferir 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).
**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>`.