Corrigir documentação técnica pelas regras do projeto sem quebrar links

## Separar arquivos editáveis dos gerados automaticamente antes de editar - Identifique onde ficam o conteúdo redigido, as inclusões reutilizáveis, os modelos, os dados estruturados, os recursos estáticos e as referências geradas. - Trate o guia de contribuição, o guia de estilo, a referência de componentes e as regras de metadados de cabeçalho do repositório como fontes oficiais. - Antes de fazer uma alteração, diferencie fontes editáveis de conteúdo incorporado de terceiros ou gerado. - Não edite diretamente arquivos incorporados de terceiros nem páginas de referência geradas. Rastreie-os até a fonte original e faça a correção nela. - Quando uma falha de validação local tiver origem em conteúdo protegido, informe a fonte original responsável em vez de aplicar uma solução alternativa local. ## Usar caminhos reais de arquivo nos links e conferir cada destino - Determine se o sistema de publicação reescreve caminhos de origem, remove partes deles ou atribui aliases. - Use o caminho de origem completo nas referências internas quando o sistema de compilação resolver links com base na árvore de fontes, mesmo que a URL pública seja mais curta. - Compare as âncoras com os identificadores de título gerados pelo renderizador real, incluindo as regras de conversão para minúsculas e de formação de slugs. - Verifique os links substitutos em vez de adivinhá-los. Se não for possível confirmar o destino, considere a alteração bloqueada, a menos que uma migração consolidada permita usar com segurança uma URL sem âncora. - Antes de alterar a referência a um recurso ausente, inspecione o sistema de arquivos virtual do framework e os recursos fornecidos pelas dependências, além da pasta de fontes visível. ## Escrever frases curtas e diretas com os termos aprovados do projeto - Escreva de forma direta, concisa e na voz ativa. - Remova expressões evasivas, conteúdo promocional de preenchimento, comentários sobre o próprio texto e formulações que descrevam uma tarefa como isenta de esforço. - Dê preferência a instruções centradas no leitor e nomeie o produto ou sistema quando for necessário explicitar a propriedade. - Use a terminologia, a capitalização, os verbos de interface e as regras de ênfase aprovados pelo repositório. - Mantenha notas permanentes de introdução de versão quando explicarem quando um comportamento começou; evite expressões relativas cujo significado expire com o tempo. - Adicione termos técnicos legítimos à lista de vocabulário permitido mais restrita. Use a grafia canônica e evite padrões amplos que suprimam verificações não relacionadas. ## Preencher título e descrição de cada página e escrever os componentes corretamente - Inclua todos os campos de metadados obrigatórios, como título da página, descrição para visualização prévia e palavras-chave de pesquisa. - Mantenha os rótulos de navegação dentro dos limites documentados e use campos de ordenação somente quando a seção exigir. - Consulte a referência de componentes antes de escrever códigos abreviados do framework ou componentes incorporados; uma sintaxe inválida pode falhar silenciosamente e produzir conteúdo danificado. - Siga o comportamento documentado das diretivas de interface no lado do cliente. Não combine dois mecanismos de ocultação quando um puder anular o outro permanentemente; use o padrão de ocultação anterior à inicialização do framework. - Não altere a configuração global apenas para contornar uma limitação da compilação local ou da árvore de trabalho. ## Formatar e verificar primeiro os arquivos alterados e depois o site todo se preciso - Depois de editar, execute o formatador fornecido pelo repositório nos arquivos alterados. - Antes de uma validação mais ampla, execute o verificador limitado aos arquivos que combina verificações de marcação e de texto. - Durante o trabalho incremental, prefira verificações direcionadas para que falhas não relacionadas não ocultem o resultado. - Execute compilações completas do site e verificações de links quando a alteração afetar o roteamento, componentes compartilhados, navegação, referências geradas ou outros comportamentos entre páginas. - Em ambientes nos quais um alvo de validação unificado seja incompatível, execute separadamente as verificações compatíveis e mantenha a configuração inalterada. - Conclua a verificação aplicável sem esperar outro lembrete e informe qualquer verificação que não tenha sido possível executar. ## Fazer uma mudança pequena por problema e responder a cada comentário de revisão - Crie um único conjunto de alterações focado para cada problema. Não misture limpezas adjacentes nem refatorações não relacionadas às correções da documentação. - Coloque os arquivos explicitamente na área de preparação. Nunca use comandos de preparação abrangentes que possam incluir arquivos de bloqueio ou alterações geradas. - Antes de confirmar as alterações, inspecione a lista de arquivos preparados e retire tudo o que estiver fora do escopo de documentação pretendido. - Confirme que o destino de qualquer envio seja a bifurcação do colaborador ou outro repositório remoto aprovado, e não o repositório original protegido. - Trate relatos de problemas e sugestões de revisão como afirmações que precisam ser verificadas. Confirme o comportamento observado antes de alterar a documentação. - Responda a cada discussão de revisão depois de tratá-la, incluindo comentários em linhas específicas que possam exigir uma chamada separada à API de revisão. - Use o ponto de acesso do serviço que comprovadamente preserve rótulos e metadados quando um comando de conveniência não for confiável. ## Remover páginas ou adicionar uma versão nova sem deixar links quebrados - Antes de excluir uma página, pesquise seu slug, título, aliases e referências de entrada no conteúdo redigido e na configuração de navegação. - Ao avançar uma referência versionada, atualize a configuração central de versões, crie a página da nova versão e transfira para ela os aliases da versão mais recente que estavam na página anterior, tudo em uma única alteração. - Nunca permita que duas páginas de versão reivindiquem o mesmo alias da versão mais recente. - Para referências geradas, altere a especificação ou o gerador original e gere novamente o conteúdo; não edite manualmente a página gerada. - Mantenha as correções mínimas, verifique a falha real e preserve um caminho claro de escalonamento quando a propriedade ou as evidências externas continuarem sem resolução.