# Melhores práticas para documentos do GitHub

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

## Sobre a documentação de GitHub

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

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

* [Sobre a filosofia de documentação do GitHub](/pt/enterprise-server@3.22/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)
* [Sobre os conceitos básicos da documentação do GitHub](/pt/enterprise-server@3.22/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)
* [Princípios de design de conteúdo](/pt/enterprise-server@3.22/contributing/writing-for-github-docs/content-design-principles)

## Práticas recomendadas para escrever GitHub documentação

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 use os seguintes tipos de conteúdo:

* [Tipo de conteúdo de conceitos](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/concepts-content-type)
* [Tipo de conteúdo de referência](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/reference-content-type)
* [Tipo de conteúdo de instruções](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/how-to-content-type)
* [Tipo de conteúdo de solução de problemas](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/troubleshooting-content-type)
* [Tipo de conteúdo de início rápido](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/quickstart-content-type)
* [Tipo de conteúdo de tutorial](/pt/enterprise-server@3.22/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. Os termos que são bem conhecidos pelos desenvolvedores são bons, mas não suponha que o leitor saiba os detalhes de como 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](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide#voice-and-tone) e [AUTOTITLE.](/pt/enterprise-server@3.22/contributing/writing-for-github-docs/writing-content-to-be-translated)

## 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 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 de execução opcionais)
  * Listas numeradas
  * [Alertas](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide#alerts)
  * Tabelas
  * Visuais
  * Blocos de código e anotações de código

## Leitura adicional

* [Guia de estilo](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide)
* [Sobre o modelo de conteúdo](/pt/enterprise-server@3.22/contributing/style-guide-and-content-model/about-the-content-model)
* [Conteúdo de um artigo do GitHub Docs](/pt/enterprise-server@3.22/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