Melhores práticas para documentos do GitHub

Siga estas melhores práticas para criar uma documentação fácil de usar e de entender.

Neste artigo

Sobre a documentação do GitHub

Em GitHub, nos esforçamos para criar documentação precisa, valiosa, inclusiva, acessível e fácil de usar.

Antes de contribuir para GitHub Docs, reserve um momento para se familiarizar com a filosofia de documentação, os princípios básicos e os princípios de design de conteúdo da GitHub.

Práticas recomendadas para gravação da documentação de GitHub

Se você estiver criando um novo artigo ou atualizando um existente, siga estas diretrizes ao fazer a gravação para GitHub Docs:

Alinhar o conteúdo às necessidades do usuário

Antes de começar, é importante entender para quem você está escrevendo, quais são seus objetivos, as principais tarefas ou conceitos que o artigo abordará e que tipo de conteúdo escrever.

Definir o público-alvo

  • Quem vai ler esse conteúdo?
  • O que ele está tentando fazer?

Definir o objetivo principal

  • O que alguém deve ser capaz de fazer ou entender depois de ler este artigo? Escolha uma ou duas tarefas ou conceitos que o conteúdo discutira.
  • Se houver tarefas, conceitos ou informações adicionais que não sejam essenciais, considere se elas podem ser colocadas abaixo no artigo, movidas para outro artigo ou omitidas completamente.

Determinar o tipo de componente

Determine que tipo de conteúdo você escreverá, com base no público-alvo e no objetivo principal do conteúdo. GitHub Docs usam os tipos de conteúdo a seguir:

Por exemplo, use o tipo de conteúdo conceitual para ajudar os leitores a entender os conceitos básicos de um recurso ou tópico e como ele pode ajudá-los a atingir suas metas. Use o tipo de conteúdo de procedimento para ajudar as pessoas a concluir uma tarefa específica do início ao fim.

Estruture o conteúdo para facilitar a leitura

Use as práticas recomendadas a seguir para estruturar o conteúdo. Ao adicionar conteúdo a um artigo existente, siga a estrutura existente sempre que possível.

  • Forneça o contexto inicial. Defina o tema e declare sua relevância para o leitor.
  • Estruture o conteúdo em uma ordem lógica por importância e relevância. Coloque as informações em ordem de prioridade e na ordem em que os usuários precisarão delas.
  • Evite frases e parágrafos longos.
    • Introduza conceitos um a um.
    • Use uma ideia por parágrafo.
    • Use uma ideia por frase.
  • Enfatize as informações mais importantes.
    • Comece cada frase ou parágrafo com as palavras e conclusões mais importantes.
    • Ao explicar um conceito, comece com a conclusão e, em seguida, explique-a com mais detalhes. (Isso às vezes é chamado de "pirâmide invertida".)
    • Ao explicar um tópico complexo, apresente aos leitores as informações básicas primeiro e divulgue os detalhes mais adiante no artigo.
  • Use subtítulos significativos. Organize parágrafos relacionados em seções. Dê a cada seção um subtítulo que seja exclusivo e que descreva com precisão o conteúdo.
  • Considere o uso de links na página para conteúdo mais longo. Isso permite que os leitores pulem para áreas de interesse e pulem conteúdo que é irrelevante para eles.

Escrever para facilitar a leitura

Facilite a leitura e a compreensão do texto por usuários ocupados.

  • Use linguagem simples. Use palavras comuns e cotidianas e evite jargões quando possível. Termos que são bem conhecidos pelos desenvolvedores são bons, mas não assuma que o leitor conheça os detalhes de como o GitHub funciona.
  • Use a voz ativa.
  • Seja conciso.
    • Escreva frases simples e breves.
    • Evite frases complexas que contenham vários conceitos.
    • Limite detalhes desnecessários.

Para obter informações relacionadas, consulte "Voz e tom" em Guia de estilo e AUTOTITLE.

Formato para escaneabilidade

A maioria dos leitores não consome artigos em sua totalidade. Em vez disso, eles fazem scanning na página para localizar informações específicas ou fazem skimming na página para ter uma ideia geral dos conceitos.

Ao fazer scanning ou skimming no conteúdo, os leitores ignoram grandes partes do texto. Procuram elementos relacionados à tarefa ou que se destacam na página, como títulos, alertas, listas, tabelas, blocos de código, elementos visuais e as primeiras palavras em cada seção.

Uma vez que o artigo tenha um propósito e uma estrutura claramente definidos, você pode aplicar as seguintes técnicas de formatação para otimizar o conteúdo para scanning e skimming. Essas técnicas também podem ajudar a tornar o conteúdo mais compreensível para todos os leitores.

  • Use o realce de texto, como negrito e hiperlinks, para chamar a atenção para os pontos mais importantes. Use o realce de texto com moderação. Não destaque mais de 10% do texto total de um artigo.
  • Use elementos de formatação para separar o conteúdo e criar espaço na página. Por exemplo:
    • Listas com marcadores (com subtítulos de execução opcionais)
    • Listas numeradas
    • Alertas
    • Tabelas
    • Visuais
    • Blocos de código e anotações de código

Leitura adicional