Tipo de conteúdo de tutorial

Os tutoriais ajudam as pessoas a aprender mais sobre os produtos e resolver problemas do mundo real, orientando-as em todo o fluxo de trabalho a fim de realizar uma tarefa. Eles trazem um tom mais conversacional do que outros tipos de conteúdo. Um tutorial parece uma conversa entre desenvolvedores, ao mesmo tempo em que permanece acessível aos leitores com conhecimento técnico variado. Os produtos com tutoriais já precisam ter um guia de início rápido. Para fluxos de trabalho pequenos, use o modelo de início rápido.

Eles se destinam às pessoas que desejam receber recomendações de especialistas e ver uma discussão detalhada sobre as melhores práticas relacionadas ao problema. Os tutoriais também ajudam as pessoas que implementaram soluções semelhantes no passado com o uso de outros produtos do GitHub. Também podem ajudar as pessoas a confirmar se a solução é apropriada para as respectivas necessidades.

Em conjunto, nós nos referimos aos tutoriais e aos guias de início rápido como "guias" em todo o site. Nas páginas de aterrissagem de /guides, incluímos tutoriais, guias de início rápido e alguns artigos de procedimentos na lista de guias de um conjunto de documentação.

Como escrever um tutorial

Para o modelo de tutorial, consulte "Modelos".

Conteúdo dos tutoriais:

• Introdução
  • Esclarece quem é o público-alvo.
  • Indica claramente os pré-requisitos e o conhecimento prévio necessário.
  • Indica o que alguém realizará ou criará.
  • Inclui um exemplo de um projeto bem-sucedido.
  • Não inclui o tempo esperado que pode levar alguém para realizar a tarefa. Isso depende do nível de experiência da pessoa que está fazendo o tutorial.
• Seções de procedimentos
  • Com base no público-alvo do tutorial, as etapas podem ser menos explícitas e formais do que aquelas usadas no conteúdo de procedimentos. Você não precisa usar reutilizáveis existentes para formar essas etapas se o público-alvo não necessita desse nível de detalhes.
    • Use: “No seu perfil, clique em Configurações e clique em Configurações do desenvolvedor.”
    • Evite: no canto superior direito de qualquer página, clique na foto do seu perfil e em Configurações. Na barra lateral esquerda, clique em Configurações do desenvolvedor.
  • Crie um link para outros artigos ou recursos em vez de replicá-los, a fim de evitar interromper o fluxo de informações no tutorial.
  • Forneça indicações visuais. Use amplamente blocos de código e capturas de tela para ajudar a tranquilizar as pessoas de que elas estão executando as ações corretas.
  • Forneça exemplos reais.
    • Por exemplo, não diga a alguém para "Inserir uma mensagem de commit". Em vez disso, dê um exemplo apropriado de mensagem de commit que corresponda às etapas anteriores.
• Solução de problemas
  • Reconheça o que pode dar errado na tarefa e liste alguns problemas comuns que os leitores podem encontrar com as soluções.
• Conclusão
  • Revise o que foi realizado ou criado. Faça referências novamente ao projeto fornecido na introdução como um exemplo de um projeto bem-sucedido.
• Próximas etapas
  • Inclua duas a três próximas etapas acionáveis que alguém poderá executar depois de concluir o tutorial. Crie links para outras informações relacionadas, como:
    • Projetos do GitHub que ilustram os conceitos introduzidos
    • Informações relevantes no docs.github.com
    • GitHub Skills relevante
    • Palestras publicadas relevantes, postagens no blog ou postagens da série no Fórum da Comunidade de Hubbers

Diretrizes de título para tutoriais

• Siga as diretrizes de título para artigos de procedimentos.
• Não use "tutorial" nem "guia" no título.

Exemplos de tutoriais

Tutoriais:

• Adicionando etiquetas a problemas
• Instalar um certificado da Apple em executores do macOS para desenvolvimento do Xcode

Guias de linguagens e estruturas:

• Criar e testar Node.js
• Criar e testar o Python
• Publicar pacotes Java com Maven