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.

  •         [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)

  •         [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)

  •         [AUTOTITLE](/contributing/writing-for-github-docs/content-design-principles)

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

Se você estiver criando um novo artigo ou atualizando um existente, siga estas diretrizes ao escrever para GitHub Docs:

  •         [Alinhar o conteúdo às necessidades do usuário](#align-content-to-user-needs)

  •         [Estruture o conteúdo para facilitar a leitura](#structure-content-for-readability)

  •         [Escrever para facilitar a leitura](#write-for-readability)

  •         [Formato para escaneabilidade](#format-for-scannability)

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:

  •         [Conteúdo conceitual](/contributing/style-guide-and-content-model/conceptual-content-type)

  •         [Conteúdo referencial](/contributing/style-guide-and-content-model/referential-content-type)

  •         [Conteúdo de procedimentos](/contributing/style-guide-and-content-model/procedural-content-type)

  •         [Conteúdo de solução de problemas](/contributing/style-guide-and-content-model/troubleshooting-content-type)

  •         [Início rápido](/contributing/style-guide-and-content-model/quickstart-content-type)

  •         [Tutorial](/contributing/style-guide-and-content-model/tutorial-content-type)

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 escaneiam a página para localizar informações específicas ou percorrem a página por alto para ter uma ideia geral dos conceitos.

Ao realizar escaneamento ou leitura dinâmica 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 uma leitura rápida e superficial. 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 opcionais incorporados)
    • Listas numeradas
    •       [Alertas](/contributing/style-guide-and-content-model/style-guide#alerts)
    • Tabelas
    • Visuais
    • Blocos de código e anotações de código

Leitura adicional

  •         [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)

  •         [AUTOTITLE](/contributing/style-guide-and-content-model/about-the-content-model)

  •         [AUTOTITLE](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article)

  •         [Diretrizes de legibilidade](https://readabilityguidelines.co.uk/), Design de Conteúdo de Londres

  •         [Reescrevendo Conteúdo Digital para Brevidade](https://www.nngroup.com/articles/rewriting-content-brevity/), Grupo Nielsen Norman