{"meta":{"title":"Melhores práticas para documentos do GitHub","intro":"Siga estas melhores práticas para criar uma documentação fácil de usar e de entender.","product":"Contribuir com o GitHub Docs","breadcrumbs":[{"href":"/pt/contributing","title":"Contribuir com o GitHub Docs"},{"href":"/pt/contributing/writing-for-github-docs","title":"Escrevendo para GitHub Docs"},{"href":"/pt/contributing/writing-for-github-docs/best-practices-for-github-docs","title":"Melhores práticas para documentos do GitHub"}],"documentType":"article"},"body":"# Melhores práticas para documentos do GitHub\n\nSiga estas melhores práticas para criar uma documentação fácil de usar e de entender.\n\n## Sobre a documentação de GitHub\n\nEm , GitHubnós nos esforçamos para criar uma documentação precisa, valiosa, inclusiva, acessível e fácil de usar.\n\nAntes 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:\n\n* [Sobre a filosofia de documentação do GitHub](/pt/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)\n* [Sobre os conceitos básicos da documentação do GitHub](/pt/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)\n* [Princípios de design de conteúdo](/pt/contributing/writing-for-github-docs/content-design-principles)\n\n## Práticas recomendadas para escrever GitHub documentação\n\nSe você estiver criando um novo artigo ou atualizando um existente, siga estas diretrizes ao escrever para GitHub Docs:\n\n* [Alinhar o conteúdo às necessidades do usuário](#align-content-to-user-needs)\n* [Estruture o conteúdo para facilitar a leitura](#structure-content-for-readability)\n* [Escrever para facilitar a leitura](#write-for-readability)\n* [Formato para escaneabilidade](#format-for-scannability)\n\n## Alinhar o conteúdo às necessidades do usuário\n\nAntes 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.\n\n### Definir o público-alvo\n\n* Quem vai ler esse conteúdo?\n* O que ele está tentando fazer?\n\n### Definir o objetivo principal\n\n* 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.\n* 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.\n\n### Determinar o tipo de componente\n\nDetermine que tipo de conteúdo você escreverá, com base no público-alvo e no objetivo principal do conteúdo.\nGitHub Docs use os seguintes tipos de conteúdo:\n\n* [Tipo de conteúdo de conceitos](/pt/contributing/style-guide-and-content-model/concepts-content-type)\n* [Tipo de conteúdo de referência](/pt/contributing/style-guide-and-content-model/reference-content-type)\n* [Tipo de conteúdo de instruções](/pt/contributing/style-guide-and-content-model/how-to-content-type)\n* [Tipo de conteúdo de solução de problemas](/pt/contributing/style-guide-and-content-model/troubleshooting-content-type)\n* [Tipo de conteúdo de início rápido](/pt/contributing/style-guide-and-content-model/quickstart-content-type)\n* [Tipo de conteúdo de tutorial](/pt/contributing/style-guide-and-content-model/tutorial-content-type)\n\nPor 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.\n\n## Estruture o conteúdo para facilitar a leitura\n\nUse 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.\n\n* **Forneça o contexto inicial**. Defina o tema e declare sua relevância para o leitor.\n* **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.\n* **Evite frases e parágrafos longos**.\n  * Introduza conceitos um a um.\n  * Use uma ideia por parágrafo.\n  * Use uma ideia por frase.\n* **Enfatize as informações mais importantes**.\n  * Comece cada frase ou parágrafo com as palavras e conclusões mais importantes.\n  * 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\".)\n  * Ao explicar um tópico complexo, apresente aos leitores as informações básicas primeiro e divulgue os detalhes mais adiante no artigo.\n* **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.\n* **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.\n\n## Escrever para facilitar a leitura\n\nFacilite a leitura e a compreensão do texto por usuários ocupados.\n\n* **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.\n* Use a voz ativa.\n* **Seja conciso.**\n  * Escreva frases simples e breves.\n  * Evite frases complexas que contenham vários conceitos.\n  * Limite detalhes desnecessários.\n\nPara obter informações relacionadas, consulte \"Voz e tom\" em [Guia de estilo](/pt/contributing/style-guide-and-content-model/style-guide#voice-and-tone) e [AUTOTITLE.](/pt/contributing/writing-for-github-docs/writing-content-to-be-translated)\n\n## Formato para escaneabilidade\n\nA 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.\n\nAo 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.\n\nUma 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.\n\n* **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.\n* **Use elementos de formatação** para separar o conteúdo e criar espaço na página. Por exemplo:\n  * Listas com marcadores (com subtítulos de execução opcionais)\n  * Listas numeradas\n  * [Alertas](/pt/contributing/style-guide-and-content-model/style-guide#alerts)\n  * Tabelas\n  * Visuais\n  * Blocos de código e anotações de código\n\n## Leitura adicional\n\n* [Guia de estilo](/pt/contributing/style-guide-and-content-model/style-guide)\n* [Sobre o modelo de conteúdo](/pt/contributing/style-guide-and-content-model/about-the-content-model)\n* [Conteúdo de um artigo do GitHub Docs](/pt/contributing/style-guide-and-content-model/contents-of-a-github-docs-article)\n* [Diretrizes de legibilidade](https://readabilityguidelines.co.uk/), Design de Conteúdo de Londres\n* [Reescrevendo Conteúdo Digital para Brevidade](https://www.nngroup.com/articles/rewriting-content-brevity/), Grupo Nielsen Norman"}