Compartilhar via

Aprimoramentos de qualidade de contribuição

Você não precisa ser um especialista em assuntos ou um especialista em documentação para contribuir. Se você vir uma oportunidade de melhorar a documentação, envie um pull request com o aprimoramento proposto. Este guia descreve várias maneiras simples de qualquer pessoa contribuir com melhorias de qualidade para a documentação.

Estamos nos concentrando nessas á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 um limite de código de aspas triplas (```).
  • O comprimento da linha para blocos de código é limitado a caracteres 90 para artigos de referência de cmdlet.
  • O comprimento da linha para blocos de código é limitado a caracteres 76 para artigos about_*.
  • Evite usar caracteres de continuação de linha (`) nos exemplos de código do PowerShell.
    • Use nivelamentos ou oportunidades naturais de quebra de linha, como caracteres após o pipe (|), chaves de abertura (}), parênteses (() e colchetes ([) para limitar o comprimento da linha.
  • Inclua o prompt do PowerShell apenas 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.

Formatação da sintaxe do comando

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

  • Sempre use o nome completo, sem abreviações, para cmdlets e parâmetros. Evite usar aliases, a menos que esteja demonstrando especificamente o alias.
  • Propriedade, parâmetro, objeto, nomes de tipo, nomes de classe, métodos de classe estar em negrito.
    • Os valores de propriedade e de parâmetro devem ser dispostos entre aspas invertidas (`).
    • Ao se referir a tipos que usam o estilo entre colchetes, use aspas invertidas. Por exemplo: [System.Io.FileInfo]
  • Os nomes dos módulos do PowerShell devem ser em negrito.
  • As palavras-chave e os operadores do PowerShell devem estar todos em letras minúsculas.
  • Use maiúsculas apropriadas (Pascal) para nomes e parâmetros de cmdlet.
  • Quando se referir a um parâmetro por nome, o nome deve estar em negrito.
  • Use o nome do parâmetro com o hífen se estiver ilustrando a sintaxe. Encapsule o parâmetro em aspas.
  • Quando você mostra um exemplo de uso de um comando externo, o exemplo deve ser colocado entre aspas invertidas. Sempre inclua a extensão do arquivo do comando externo.

Para facilitar a manutenção e a leitura da fonte markdown da nossa documentação, estamos convertendo nossa documentação conceitual para usar referências de links no lugar de links embutidos.

Por exemplo, em vez de:

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

Ele deveria ser:

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

Observação

Quando você substituir um link embutido, faça o refluxo do conteúdo para que ele envolva 100 caracteres. Você pode usar a extensão VS Code reflow-markdown para fazer o refluxo rapidamente do parágrafo.

Na parte inferior do arquivo, adicione um comentário de markdown 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 duplicar definições de referência de link. 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 de referência de link estão na parte inferior do arquivo após o comentário de markdown e estão na ordem numérica.

Lint de markdown

Para qualquer artigo em um dos repositórios participantes, abrir o artigo no VS Code exibe avisos de lint. Aborde qualquer um desses avisos que você encontrar, exceto:

Certifique-se dos comprimentos das linhas e use a extensão do Refluxo markdown para corrigir as longas filas.

Ortografia

Apesar dos nossos maiores esforços, erros de digitação e de ortografia acabam sendo incluídos na documentação. Esses erros tornam a documentação mais difícil de acompanhar e localizar. A correção desses erros torna a documentação mais legível, especialmente para quem não fala inglês e depende de traduções precisas.

  • Last updated on