Escrever documentação técnica em reStructuredText com exemplos reais e verificar a compilação

## Explique o que o leitor precisa e deixe os detalhes internos para o código Escreva para leitores que precisam entender e usar o comportamento documentado. Explique os conceitos com clareza e da forma mais concisa possível. Inclua detalhes de baixo nível quando ajudarem o leitor a tomar uma decisão, mas deixe os aspectos internos muito profundos da implementação para o código-fonte. - Descreva a assinatura de um método somente quando ela for essencial para o uso correto do método. - Documente os argumentos e as opções do comando que afetam o fluxo de trabalho principal, não todos os parâmetros disponíveis. - Não repita a explicação de um erro ou de uma exceção quando a mensagem no código já informar a causa e a solução. - Prefira uma explicação focada, um exemplo realista e um link para detalhes relacionados em vez de um catálogo completo. ## Escolha a ramificação pelo tipo de mudança e pelos dados de versão Nunca fixe no código a lista de versões mantidas. Leia os metadados oficiais de lançamento do projeto antes de escolher a ramificação de destino e depois aplique de forma consistente as regras do tipo de alteração. - Correções de erros devem ir para a ramificação mantida mais antiga que contenha o erro. - A documentação de um novo recurso deve ir para a ramificação que introduziu o recurso. Se essa ramificação não for mais mantida, use a próxima ramificação que ainda seja mantida. - Erros de digitação, reformulações, reestruturações e outras alterações não funcionais devem ir para a ramificação mantida mais antiga. - A documentação de subprojetos com versionamento independente segue a própria política declarada; quando essa política exigir, direcione todas as alterações para a ramificação mantida mais antiga, inclusive novos recursos. Registre o tipo de alteração e os dados de manutenção usados na decisão. Se os metadados de lançamento não estiverem disponíveis ou forem ambíguos, não adivinhe a ramificação. ## Use sempre os mesmos sinais de título e a mesma largura de linha Use de forma consistente os caracteres de sublinhado de cada nível de título: sinais de igual para o nível 1, hífens para o nível 2, tils para o nível 3, pontos para o nível 4 e aspas duplas para o nível 5. Cada sublinhado deve cobrir todo o comprimento do texto do título. Aplique qualquer exceção de título específica de caminho declarada pelo repositório. Quebre o texto em 80 caracteres, exceto em tabelas, URLs e linhas isoladas quando a quebra reduzir a legibilidade. Mantenha os marcadores de lista no início da linha. Não divida trechos em negrito ou itálico entre várias linhas. Para código em linha, use pares de crases duplas. Em exemplos de código com a linguagem padrão, use a forma concisa de dois-pontos duplos, a menos que o marcador ficasse sozinho na linha. Use uma diretiva code-block explícita quando for necessário indicar a linguagem ou o contexto de renderização. ## Padronize o recuo das diretivas e a forma de escrever links Recue o conteúdo das diretivas em quatro espaços. Deixe uma linha em branco depois de um marcador de dois-pontos duplos e antes do conteúdo, além de uma linha em branco antes e depois de cada diretiva. Alinhe as linhas de continuação de um item de lista com várias linhas ao início do texto desse item. Use a diretiva de aviso padrão adequada à mensagem: note, tip, warning, caution ou seealso. Para conteúdo adicionado em uma versão e conteúdo obsoleto, use as diretivas específicas com a versão correspondente e uma explicação curta. Use caminhos absolutos de documentos em links internos. Ao criar um link para uma seção específica, use uma referência cruzada com rótulo. Nunca use um caminho interno relativo. Para sites externos, coloque os destinos de links nomeados no final do arquivo em vez de incorporar URLs no texto. Use os papéis específicos do sistema de documentação para classes, métodos, funções e tipos integrados da API da linguagem. ## Mostre exemplos de configuração como YAML e XML sempre na mesma ordem Quando um recurso aceitar vários formatos de configuração, mostre todos os formatos compatíveis em uma diretiva configuration-block. Mantenha uma ordem comum em todo o repositório para que os leitores comparem páginas sem precisar reaprender a disposição. - Para serviços e configuração geral, use YAML, XML e depois o formato da linguagem de programação. - Para roteamento, validação e mapeamento de objetos, use atributos, YAML, XML e depois o formato da linguagem de programação. - Para recursos de tradução, use XML, YAML e depois o formato da linguagem de programação. Use abas comuns apenas para conteúdo paralelo que não seja configuração, como ferramentas ou fluxos de trabalho alternativos. Quando os exemplos forem diferentes entre aplicativos integrados ao framework e aplicativos independentes, use identificadores de linguagem distintos para que o renderizador e o leitor diferenciem os contextos. ## Escreva exemplos de código com nomes realistas e um comentário com o arquivo Siga os padrões de codificação da linguagem de destino e as práticas recomendadas estabelecidas pelo projeto. Use nomes e cenários realistas em vez de palavras de preenchimento que escondam a intenção. Use domínios reservados para exemplos e o nome de fornecedor de exemplo adotado pelo repositório. - Quebre as linhas dos blocos de código em 85 caracteres quando for prático. - Recue os exemplos em quatro espaços, inclusive YAML. - Inclua declarações de namespace e import quando ajudarem a executar o exemplo ou esclarecer os tipos. - Inicie um bloco de código com um comentário que informe o nome do arquivo; não acrescente uma linha em branco, a menos que a próxima linha também seja um comentário. - Coloque um marcador de linha de comando antes de cada comando de shell. - Use a forma de comentário adequada à linguagem ao resumir blocos omitidos. - Use reticências sem marcadores de comentário ao encurtar parte de um valor na mesma linha. - Preserve as regras de espaçamento específicas do formato, inclusive os espaços dentro de mapeamentos YAML em linha quando forem necessários. Um exemplo deve ensinar o caminho compatível sem fingir que é uma implementação completa para produção. Não omita um pré-requisito cuja ausência faria o código apresentado falhar. ## Escreva em inglês americano simples e evite palavras como “simply” Escreva em inglês americano. Use capitalização de título nos títulos das seções: coloque em maiúscula a primeira e a última palavra e as palavras principais, deixando as palavras funcionais curtas em minúscula, salvo quando iniciarem o título. Dirija-se ao leitor como “you” em vez de falar como “we”. Use pronomes neutros em relação a gênero. Prefira voz ativa, vocabulário básico e frases diretas que funcionem para um público internacional. Contrações são permitidas. Não use a vírgula de Oxford. Evite expressões idiomáticas e palavras condescendentes como “obviously”, “simply”, “just”, “easy”, “clearly”, “trivial” e “of course”. Essas palavras podem esconder uma explicação insuficiente e desmotivar o leitor. Toda imagem precisa de um texto alternativo conciso que comece com letra maiúscula e termine com ponto. Não comece com “A screenshot of” nem “Diagram of”. Explique diagramas complexos no texto ao redor, em vez de forçar todos os detalhes no texto alternativo. ## Antes de terminar, compile a documentação e confira avisos e links quebrados Escreva diretórios com uma barra no final e extensões de arquivo com um ponto no início. Use uma raiz de projeto de exemplo neutra, como `your-project/`, em árvores de diretórios. Mantenha nomes de arquivo, caminhos, comandos e destinos de referência consistentes entre o texto e os exemplos. Antes de considerar uma alteração na documentação concluída: 1. Instale as dependências de compilação da documentação no espaço de trabalho de compilação designado. 2. Execute o comando de compilação documentado pelo repositório. 3. Disponibilize temporariamente o resultado gerado quando for necessária uma inspeção visual. 4. Verifique nas páginas alteradas avisos, referências quebradas, diretivas malformadas, renderização de código, hierarquia de títulos e descrições de imagens. 5. Confirme que a ramificação de destino escolhida ainda corresponde ao tipo de alteração e aos metadados de manutenção atuais. Não informe sucesso apenas com base na inspeção do código-fonte quando o repositório oferecer um mecanismo de compilação da documentação.