Escrever páginas curtas que mostram os usos mais comuns de um comando

## Procurar se a página já existe e escolher a pasta conforme o sistema Pesquise o comando em todas as árvores de páginas originais e traduzidas antes de criar qualquer conteúdo. Se já existir uma página, edite-a em vez de criar uma duplicata. Se não existir, determine onde a sintaxe documentada realmente funciona. - Coloque um comando no diretório comum somente quando a mesma sintaxe funcionar em pelo menos duas plataformas. - Coloque um comando que funciona em uma única plataforma no diretório dessa plataforma. - Mantenha as páginas em inglês na árvore principal e as traduções em árvores específicas de cada localidade, com o mesmo caminho de plataforma. - Use nomes de arquivo em letras minúsculas, a menos que uma política específica da plataforma exija a capitalização canônica do comando no título da página ou na invocação. Não escolha um diretório pela reputação ou pelo nome do comando. Primeiro, verifique as plataformas compatíveis e a sintaxe. ## Manter a página curta, com título e descrição antes dos exemplos Escreva cada página como uma pequena referência Markdown com esta sequência fixa: 1. Um único H1 cujo nome de comando corresponda ao nome do arquivo, ignorando diferenças entre maiúsculas e minúsculas quando o repositório permitir. 2. Uma descrição em bloco de citação, de preferência com uma ou duas linhas. 3. Uma linha obrigatória de “Mais informações” contendo uma URL da fonte original entre sinais de menor e maior. 4. Exemplos práticos, cada um com uma descrição em forma de item e no modo imperativo, seguida por uma linha separada com o comando em código embutido. 5. Uma quebra de linha no final do arquivo. Use cinco exemplos como padrão e nunca ultrapasse oito. Mantenha uma linha em branco entre a descrição e o comando e entre os exemplos. Não use negrito, itálico nem Markdown decorativo no conteúdo da página. ## Escolher exemplos para as tarefas reais mais comuns Selecione exemplos que resolvam as tarefas reais mais comuns. Escreva as descrições no modo imperativo: “Liste arquivos”, não “Lista arquivos”. Mantenha-as curtas e orientadas à ação e não explique conceitos gerais do sistema operacional. Verifique cada exemplo no manual do comando, na ajuda integrada ou na documentação oficial. Preserve o espaçamento documentado entre opções e argumentos; use `--option arg`, a menos que o comando exija explicitamente outra forma. Coloque “Exibir ajuda” e “Exibir versão” como os dois últimos exemplos, nessa ordem, quando essas invocações existirem. Eles têm prioridade menor; portanto, omita um deles quando for necessário incluir um exemplo prático mais útil e o limite da página for ultrapassado. ## Marcar com chaves duplas as partes que o usuário deve trocar Envolva os valores substituíveis em chaves duplas. Use consistentemente os seguintes formatos semânticos de marcadores de posição: - `{{path/to/file}}`, `{{path/to/directory}}` e `{{filename}}` para entradas do sistema de arquivos; - `{{file1 file2 ...}}` para vários argumentos; - `{{option1|option2}}` para alternativas; - `{{1..5}}` para intervalos numéricos e `{{*.ext}}` para padrões com curingas; - `{{[-v|--verbose]}}` para opções curtas e longas equivalentes; - `{{[-it|--interactive --tty]}}` para sinalizadores agrupados. Quando existirem formas curta e longa, mostre ambas. Nunca invente uma forma curta: sinalizadores de versão e outras opções comuns variam conforme o comando. Não aninhe marcadores de posição nem substitua a sintaxe obrigatória de chaves duplas por chaves simples ou colchetes. Use sinais de menor e maior para representar teclas pressionadas: `<a>`, `<Enter>`, `<Space>`, `<Ctrl>`, `<Alt>` e `<Shift>`. Escreva combinações com um espaço, como `<Ctrl c>`, e sequências como grupos adjacentes, como `<Esc><u>`. ## Conferir se o link abre e depois apontar para o manual oficial Toda página deve incluir um link para mais informações. Prefira o manual oficial do comando, a documentação do projeto, um serviço de páginas de manual mantido ativamente ou a documentação do fornecedor da plataforma. Antes de aceitar um link, siga os redirecionamentos e confirme que a resposta final foi bem-sucedida. Não confie em uma URL apenas porque ela parece plausível. Mantenha o link entre sinais de menor e maior na linha exclusiva de “Mais informações” e evite fontes promocionais ou não oficiais quando houver uma fonte primária. Use as mesmas fontes confiáveis para confirmar nomes de comandos, formatos de opções, espaçamento de argumentos, comportamento em cada plataforma, sintaxe de ajuda e sintaxe de versão. ## Escrever caminhos e variáveis do jeito que o Windows e outros sistemas esperam Nas páginas de comandos do Windows, mantenha os nomes de arquivo em letras minúsculas, a menos que a política do repositório determine o contrário, mas preserve a capitalização canônica do comando no H1 e nos exemplos. Use barras invertidas nos marcadores de posição de caminhos. Escreva as variáveis de ambiente na sintaxe do shell documentado: `%VARIABLE%` para o interpretador de comandos tradicional e `$Env:VARIABLE` para o PowerShell. Os exemplos destinados ao PowerShell devem funcionar tanto na edição mais antiga com suporte quanto na edição atual, a menos que a página declare um requisito mais restrito. Em outras plataformas, siga as convenções nativas de caminhos, shell, variáveis de ambiente e opções. Uma página compartilhada só é válida quando a sintaxe de comando apresentada for realmente portátil. ## Criar páginas para os outros nomes e os subcomandos de um comando Crie páginas de alias com o utilitário de aliases do repositório, quando houver um. Informe que o comando é um alias, inclua um link para as informações da fonte original e forneça um exemplo que abra a página de referência do comando original. Mantenha as páginas de alias traduzidas sincronizadas por meio do mesmo utilitário, em vez de editar suas estruturas geradas de forma independente. Para comandos com subcomandos, mencione na descrição da página principal os subcomandos representativos que tenham páginas separadas. Crie para cada subcomando documentado uma página própria com nome separado por hifens e inclua um exemplo que abra a referência do subcomando correspondente. Não sobrecarregue a página principal com fluxos de trabalho detalhados de subcomandos que pertencem às páginas específicas deles. ## Traduzir a página sem mudar os comandos nem a estrutura Traduza somente depois que a página em inglês existir. Mantenha a mesma estrutura de exemplos, o caminho de plataforma, os comandos e os marcadores de posição. Não altere domínios reservados para exemplos e mantenha as palavras dos marcadores de posição no idioma de origem quando a política do repositório exigir. Aplique regras de redação específicas da localidade em vez de copiar mecanicamente a gramática inglesa. Por exemplo: - O chinês separa o texto em alfabeto latino e os números do texto chinês com espaços e usa pontuação de largura completa. - O francês usa descrições de exemplos na terceira pessoa e um espaço antes dos sinais de pontuação que assim o exigem. - O espanhol usa descrições na terceira pessoa e os termos técnicos localizados preferenciais. - O português brasileiro e o europeu usam descrições na terceira pessoa. - O indonésio usa a forma concisa de descrição de comandos, sem prefixos verbais desnecessários. Valide a página traduzida com as mesmas verificações estruturais usadas na fonte em inglês. ## Conferir a página com o verificador antes da revisão por uma pessoa Execute o linter de páginas do repositório no arquivo alterado antes de solicitar revisão humana. Use um lint da árvore completa somente quando a alteração ou a política do repositório exigir. Revise a página para confirmar: - que o título e o nome do arquivo correspondam; - que a descrição em bloco de citação seja curta e contenha um link de informações válido; - que haja cinco exemplos preferenciais e não mais de oito; - que as descrições estejam no modo imperativo e as linhas em branco estejam corretas; - que os formatos das opções tenham sido verificados e os marcadores de posição usem chaves duplas; - que o diretório da plataforma esteja correto e a sintaxe seja nativa; - que os exemplos de ajuda e versão estejam nas posições finais, quando incluídos; - que não haja formatação decorativa; - que as traduções sigam as regras específicas da localidade; - que haja uma quebra de linha final. Use os scripts de manutenção do repositório, quando disponíveis, para atualizações mecânicas de títulos, links, aliases, referências cruzadas e comandos. Prefira o modo dry-run antes de uma alteração ampla executada por script. ## Dar à IA o manual e páginas parecidas antes de escrever Reduza o custo da IA e os ciclos de correção fornecendo evidências antes da redação. Inclua a saída da ajuda ou do manual do comando, indique duas ou três páginas semelhantes já aprovadas e forneça o modelo da página, em vez de pedir ao agente que se lembre das convenções. Primeiro, verifique se já existe uma página. Agrupe solicitações de páginas relacionadas quando elas compartilharem contexto, mas revise cada página de forma independente. Redija cinco ou seis exemplos de alto valor em vez de preencher o limite de oito exemplos. Execute o linter antes da revisão humana para que erros de formatação não consumam a atenção da pessoa revisora. A redução de custos deve resultar de entradas melhores, reutilização e validação determinística, nunca da omissão da verificação das fontes nem da redução da qualidade da página.