Compartilhar via

Aprimoramentos de qualidade de contribuição

Para o Hacktoberfest 2022, nós testamos um processo piloto por contribuir com melhorias de qualidade para o conteúdo do PowerShell. Este guia generaliza esse processo para definir uma forma de baixo atrito para os membros da comunidade melhorarem a qualidade da documentação.

Estamos nos concentrando nessas áreas de qualidade:

Rastreamento de Projeto

Estamos rastreando as contribuições com o Projeto GitHub de Contribuições de Qualidade dos Documentos do PowerShell.

A página do projeto tem várias exibições para os problemas e PRs relacionados a esse esforço:

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][31] displays all available
packages in the PowerShell Gallery.

Ele deveria ser:

The [Packages tab][31] 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. Os links são definidos na ordem em que aparecem no documento.
  2. Cada link aponta para o local correto.
  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 correta.

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.

Processo

Incentivamos você a escolher uma ou mais áreas de qualidade e um artigo (ou grupo de artigos) para melhorar. Use as etapas a seguir para orientar seu trabalho:

  1. Verifique o projeto para problemas registrados para essa iniciativa, a fim de evitar a duplicação de esforços.

  2. Abra um novo problema no repositório apropriado:

  3. Siga nosso guia do colaborador para se preparar para fazer suas alterações.

  4. Envie sua solicitação de pull. Assegurar:

    1. Seu título de RP tem o prefixo Quality:.

    2. O corpo do seu PR faz referência ao problema que ele resolve como um item de lista não ordenada e usa um das palavras-chave de vinculação.

      Por exemplo, se estiver trabalhando no problema 123, o corpo de seu PR deve incluir o seguinte Markdown:

      - resolves #123

    Depois que você enviar o PR, os mantenedores analisarão o seu trabalho e trabalharão com você para que ele seja mesclado.

  • Last updated on