Partilhar via

Contribuir para melhorias de qualidade

Para o Hacktoberfest 2022, conduzimos um processo para contribuir com melhorias de qualidade para o conteúdo do PowerShell. Este guia generaliza esse processo para definir uma maneira de baixo atrito para os membros da comunidade melhorarem a qualidade da documentação.

Estamos focados nas seguintes áreas de qualidade:

Acompanhamento de Projetos

Estamos a monitorizar as contribuições com o projeto do GitHub para as Contribuições de Qualidade dos Documentos do PowerShell.

A página do projeto tem várias visões para as questões e RPs relacionadas a este 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 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][31] displays all available
packages in the PowerShell Gallery.

Deve ser:

The [Packages tab][31] 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. 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.

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.

Processo

Encorajamo-lo a escolher uma ou mais das áreas de qualidade e um artigo (ou grupo de artigos) para melhorar. Use as seguintes etapas para orientar seu trabalho:

  1. Verifique o projeto para problemas arquivados para este esforço para evitar a duplicação de esforços.

  2. Abra uma nova questão no repositório apropriado.

  3. Siga o nosso guia do colaborador para obter a configuração para fazer as suas alterações.

  4. Envie o seu pull request. Assegurar:

    1. O seu título PR tem o prefixo Quality: .

    2. Seu corpo de RP faz referência ao problema que ele resolve como um item de lista não ordenado e usa uma das palavras-chave de vinculação.

      Por exemplo, se você estiver trabalhando no problema 123, o corpo do seu RP deve incluir o seguinte Markdown:

      - resolves #123

    Depois de enviar o PR, os mantenedores analisarão seu trabalho e trabalharão com você para fundi-lo.

  • Last updated on