As seguintes diretrizes ajudam a apresentar o seu conteúdo sob a forma de tutorial para que os utilizadores possam familiarizar-se eficazmente com o seu projeto.
Funcionalidades do Cloud Shell
- Esquema único: os tutoriais são apresentados num painel lateral no lado direito da consola. Google Cloud
- Navegação: os utilizadores podem avançar no tutorial através dos botões Seguinte e Anterior em cada passo. Também podem fechar o tutorial e retomar a partir do ponto onde o deixaram.
- Código para começar: pode copiar fragmentos de código diretamente para o Cloud Shell.
Uma sessão do Editor do Cloud Shell com um painel de tutorial aberto. Os utilizadores podem copiar o código diretamente para o Cloud Shell clicando num botão e podem deslocar-se entre as páginas com os botões Seguinte e Anterior.
Estilo de escrita
- Mantenha um tom leve: os tutoriais devem ser informativos e úteis, mas não demasiado formais.
- O utilizador: use pronomes na segunda pessoa (use: você, seu; não use: nós, eu, nosso, etc.)
- Explicar a causa e o efeito: quando pedir aos utilizadores que realizem um passo, explique o raciocínio por detrás da ação e o resultado esperado.
- Tenha objetivos focados: antes de escrever o conteúdo do tutorial, estabeleça um objetivo bem definido que quer que os utilizadores alcancem. Crie o seu tutorial tendo em conta este objetivo.
| Original | Revisto | Melhoria |
| Na página seguinte, vai aprender a criar um novo tutorial. | Continue para o passo seguinte para começar a configurar o tutorial. | Enfoque no utilizador; utilização da voz ativa
Utilização de linguagem descontraída |
| Execute este comando:
``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
Para apresentar uma lista tabelada de todos os seus projetos e respetivos números de ID, intitulada "Projetos", execute o seguinte comando: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` | Explicação do raciocínio antecipadamente para definir expetativas sobre o resultado |
Let's get started!
|
Let's get started!
Este guia mostra como criar o seu próprio tutorial interativo. Também explica como gerar um botão que os utilizadores podem usar para iniciar o tutorial concluído. |
Roteiro claro das aulas abordadas no tutorial
Certifique-se de que mantém este foco ao escrever conteúdo! |
Práticas recomendadas
Mantenha-o curto: as restrições de espaço únicas do painel do tutorial significam que só é possível apresentar uma quantidade limitada de informações a um utilizador de cada vez. Evite grandes blocos de texto que sejam difíceis de analisar rapidamente e que exijam deslocamento vertical. Dê preferência a informações apresentadas em blocos pequenos.
Não use mais de 5 passos e 3 fragmentos de código por página.
Idealmente, os parágrafos devem ter 5 linhas ou menos e abordar um único conceito.
Se uma página tiver de ser longa, procure que tenha, no máximo, o dobro do comprimento do painel.
O código e os blocos de terminais devem ser suficientemente pequenos para serem lidos:
- Tente ter 10 linhas ou menos.
- Tente ter 80 carateres ou menos por linha para reduzir o deslocamento horizontal.
- Evite blocos de código com vários comandos para impedir que os utilizadores tenham de fazer uma cópia e execução em massa.
Página de introdução: comece o tutorial com uma introdução.
- Defina expetativas: explique brevemente como os seus utilizadores vão beneficiar da conclusão deste tutorial.
- Tempo estimado de dedicação: estime aproximadamente quanto tempo os utilizadores podem esperar gastar no tutorial. Procure criar um tutorial que possa ser concluído em menos de 15 minutos. Se o seu tutorial for mais longo (ou consistir em mais de 15 páginas com texto denso), considere dividi-lo numa série de tutoriais mais pequenos.
- Seja direto: indique claramente os recursos ou o acesso prévios que os utilizadores podem ter de configurar para trabalhar no tutorial sem interrupções.
Exemplo ## Vamos começar!
Inclua um tutorial interativo para que os utilizadores possam começar a usar o seu projeto rapidamente.
Este guia mostra como criar o seu próprio tutorial interativo (como este). Também explica como gerar um botão que os utilizadores podem usar para iniciar o tutorial concluído.
**Tempo de conclusão**: cerca de 10 minutos
**Pré-requisitos**: uma conta do Cloud Billing
Clique no botão **Continuar** para avançar para o passo seguinte.
Página de fundo
- Defina o cenário: quando escreve um tutorial, é frequentemente útil fornecer contexto. Isto pode significar fornecer uma breve descrição geral do produto ou percorrer rapidamente as funcionalidades importantes de uma IU.
Exemplo ## O que é o Cloud Shell?
Antes de começar, vamos rever rapidamente o que o Cloud Shell pode fazer.
O Cloud Shell é uma máquina virtual alojada pessoal que é pré-carregada com ferramentas para programadores para Google Cloud produtos. Este ambiente de shell interativo inclui um editor de código integrado, armazenamento em disco persistente e funcionalidade de pré-visualização na Web. Para usar apenas o acesso à linha de comandos, visite [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).
Pode direcionar os seus utilizadores para o Cloud Shell para os ajudar a começar rapidamente a usar o seu projeto, dando-lhes a oportunidade de percorrer um exemplo de utilização e familiarizarem-se com a funcionalidade do seu projeto.
Continue para o passo seguinte para começar a configurar o tutorial.
Exemplos básicos:
- Olá mundo: o primeiro exemplo que fornecer deve ser suficientemente simples para o utilizador testar sem muita explicação. Deve ser o equivalente ao "Olá mundo". Use este exemplo como base para continuar a desenvolver e exemplificar conceitos através do tutorial.
Exemplo ## Tutoriais no contexto
O que está a ver agora é um tutorial no contexto.
O conteúdo é apresentado juntamente com o ambiente do Cloud Shell, onde pode realizar os passos do tutorial. Ter o tutorial e o ambiente de desenvolvimento abertos no mesmo local facilita o início da utilização do seu projeto por parte dos utilizadores através de uma experiência simples num único ecrã.
Experimente executar um comando agora:
```bash
echo "Hello Cloud Shell"
```
**Dica**: clique no botão de cópia na parte lateral da caixa de código para colar o comando no terminal do Cloud Shell e executá-lo.
Em seguida, escreva e inicie um tutorial básico.
Conteúdo de tutoriais
- Formate com precaução: a formatação de texto (negrito, itálico, etc.) é distrativa. Use-a apenas quando necessário e para seu benefício (para avisos, principais conclusões, etc.).
- Gramática consistente: use o imperativo ao descrever a ação do utilizador e certifique-se de que termina as frases com um ponto final.
- Referir-se a links: quando essencial para o contexto, inclua links suplementares ([texto do link](URL do link)) para que os utilizadores possam fazer a sua própria pesquisa.
- Escolha o destaque em vez das capturas de ecrã: o destaque, uma ação que realça onde os elementos da IU se encontram na Google Cloud consola, demonstra a posição para que os utilizadores possam identificar elementos sem pesquisar uma imagem.
- Vista alternativa: se possível, faculte um link para o conteúdo do tutorial oferecido como conteúdo estático. Isto dá aos utilizadores a liberdade de escolher como querem consumir as informações facultadas.
- Sugestões úteis: quando aplicável, adicione sugestões (indicadas por "**Sugestão:**") para oferecer aos utilizadores soluções mais intuitivas e práticas recomendadas.
Exemplo ## Escrever em Markdown
Para escrever o seu tutorial, use [Markdown](https://en.wikipedia.org/wiki/Markdown) e siga estas diretrizes:
### Edite o título
Modifique o título deste tutorial ("# Introduction to writing tutorials in Cloud Shell") alterando-o para:
```
# Ensina-me a escrever um tutorial
```
### Adicione um novo passo
Em seguida, adicione um passo imediatamente após o título da seguinte forma:
```
## Passo 1
Este é um novo passo que acabei de adicionar.
```
Cada "passo" de um tutorial é apresentado numa página.
**Sugestão**: para percorrer os passos, os utilizadores usam os botões "Anterior" e "Continuar/Avançar".
Resumo
- Parabéns: certifique-se de que adiciona um ícone de troféu (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) para agradecer aos utilizadores por dedicarem tempo a concluir o tutorial.
- Conclua: resuma as lições importantes que quer que os utilizadores aprendam com o tutorial.
- O que se segue: ajude os utilizadores ao longo do seu percurso fornecendo passos seguintes. Estes podem ser leituras recomendadas, recursos suplementares ou até outro tutorial.
- Cuide dos seus utilizadores: aconselhe-os a limpar todos os recursos de teste que criaram para os fins do tutorial para evitar encargos de faturação indesejados.
Exemplo ## Parabéns
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
Está tudo pronto!
Agora, pode fazer com que os utilizadores iniciem o seu tutorial no Cloud Shell e comecem a usar o seu projeto com facilidade.
Para uma lista completa das ferramentas de escrita de tutoriais do Cloud Shell, consulte a [Referência de Markdown de tutoriais](https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**Não se esqueça de limpar o que fez**: se criou projetos de teste, certifique-se de que os elimina para evitar cobranças desnecessárias. Use o comando `gcloud projects delete <PROJECT-ID>`.