Partilhar via

Contribuir para melhorias de qualidade

Não precisa de ser um especialista na matéria ou documentação para contribuir. Se vir uma oportunidade para melhorar a documentação, submeta um pull request com a melhoria proposta. Este guia apresenta várias formas simples de qualquer pessoa contribuir com melhorias de qualidade para a documentação.

Estamos focados nas seguintes áreas de qualidade:

Exemplos de código de formatação

Todos os exemplos de código devem seguir as diretrizes de estilo para o conteúdo do PowerShell. Essas regras são repetidas de forma abreviada aqui por conveniência:

  • Todos os blocos de código devem estar contidos em uma cerca de código triplo backtick (```).
  • O comprimento da linha para blocos de código é limitado a 90 caracteres em artigos de referência de cmdlet.
  • O comprimento da linha para blocos de código é limitado a 76 caracteres para about_* artigos.
  • Evite usar caracteres de continuação de linha (`) em exemplos de código do PowerShell.
    • Use espalhamento ou oportunidades de quebra de linha natural, como depois dos caracteres pipe (|), chaves de abertura (}), parênteses (() e colchetes ([) para limitar o comprimento da linha.
  • Inclua apenas o prompt do PowerShell para exemplos ilustrativos em que o código não se destina a copiar e colar.
  • Não use aliases em exemplos, a menos que esteja documentando especificamente o alias.
  • Evite usar parâmetros posicionais. Use o nome do parâmetro, mesmo que o parâmetro seja posicional.

Sintaxe do comando de formatação

Toda a prosa deve seguir as diretrizes de estilo para o conteúdo do PowerShell. Essas regras são repetidas aqui por conveniência:

  • Utilize sempre o nome completo para cmdlets e parâmetros. Evite usar aliases, a menos que você esteja demonstrando especificamente o alias.
  • Propriedade, parâmetro, objeto, nomes de tipo, nomes de classe, métodos de classe devem ser negrito.
    • Os valores de propriedade e parâmetro devem ser encapsulados em backticks (`).
    • Ao se referir a tipos que usam o estilo entre colchetes, use backticks. Por exemplo: [System.Io.FileInfo]
  • Os nomes dos módulos do PowerShell devem estar em negrito.
  • As palavras-chave e os operadores do PowerShell devem ser todos minúsculos.
  • Use a caixa apropriada (Pascal) para nomes e parâmetros de cmdlet.
  • Quando você se refere a um parâmetro pelo nome, o nome deve estar em negrito.
  • Use o nome do parâmetro com o hífen se estiver ilustrando a sintaxe. Envolva o parâmetro em backticks.
  • Quando mostras um exemplo de utilização de um comando externo, o exemplo deve ser encapsulado em backticks. Sempre inclua a extensão de arquivo do comando externo.

Para facilitar a manutenção e legibilidade da fonte de markdown para nossa documentação, estamos convertendo nossa documentação conceitual para usar referências de link em vez de links embutidos.

Por exemplo, em vez de:

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

Deve ser:

The [Packages tab][01] displays all available packages in the PowerShell Gallery.

Observação

Ao substituir um link interno, ajuste o conteúdo para envolver até 100 caracteres. Você pode usar a extensão VS Code reflow-markdown para refluir rapidamente o parágrafo.

Na parte inferior do arquivo, adicione um comentário de marcação antes da definição dos links.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Certifique-se de que:

  1. Cada link aponta para o local correto.
  2. Não duplique definições de referência de links. Se já existir uma definição de referência de link para uma URL, reutilize a referência existente em vez de criar uma nova.
  3. As definições das referências de links estão no final do ficheiro após o comentário markdown e estão na ordem numérica.

Forro Markdown

Para qualquer artigo em um dos repositórios participantes, abrir o artigo no VS Code exibe avisos de forro. Endereçe qualquer um destes avisos que encontrar, exceto:

  • MD022/blanks-around-headings/blanks-around-headers para o Synopsis cabeçalho em documentos de referência de cmdlet. Para esses itens, a violação da regra é intencional para garantir que a documentação seja compilada corretamente com o PlatyPS.

Certifique-se dos comprimentos de linha e use a extensão Reflow Markdown para corrigir quaisquer linhas longas.

Ortografia

Apesar dos nossos melhores esforços, erros ortográficos e de digitação passam e acabam na documentação. Esses erros tornam a documentação mais difícil de seguir e localizar. Corrigir esses erros torna a documentação mais legível, especialmente para falantes que não falam inglês e dependem de traduções precisas.

  • Last updated on