Lista de verificação do editor

Este artigo contém uma lista resumida de regras para escrever ou editar a documentação do PowerShell. Consulte outros artigos no Guia do Colaborador para obter explicações detalhadas e exemplos dessas regras.

Metadados

• ms.date: deve estar no formato MM/DD/YYYY
  • Alterar a data em que há uma atualização significativa ou factual
    • Reorganizando o artigo
    • Corrigindo erros factuais
    • Adicionando novas informações
  • Não altere a data se a atualização for insignificante
    • Corrigindo erros de digitação e formatação
• title: cadeia de caracteres exclusiva de 43 a 59 caracteres de comprimento (incluindo espaços)
  • Não inclua o identificador do site (ele é gerado automaticamente)
  • Use maiúsculas e minúsculas - coloque em maiúscula apenas a primeira palavra e quaisquer nomes próprios
• description: 115-145 caracteres incluindo espaços - este resumo é exibido no resultado da pesquisa

Formatação

• Elementos de sintaxe de acento grave que aparecem, embutidos, dentro de um parágrafo
  • Nomes dos cmdlets Verb-Noun
  • Variável $counter
  • Exemplos sintacticos Verb-Noun -Parameter
  • Caminhos de arquivo C:\Program Files\PowerShell, /usr/bin/pwsh
  • URLs que não devem ser clicáveis no documento
  • Valores de propriedade ou parâmetros
• Usar negrito para nomes de propriedade, nomes de parâmetro, nomes de classe, nomes de módulo, nomes de entidade, objeto ou nomes de tipo
  • Negrito é usado para marcação semântica, não ênfase
  • Negrito – usar asteriscos **
• Itálico – usar sublinhado _
  • Usado apenas para ênfase, não para marcação semântica
• Quebras de linha em 100 colunas (ou em 80 para about_Topics)
• Sem tabulações rígidas – usar somente espaços
• Sem espaços à direita nas linhas
• As palavras-chave e os operadores do PowerShell devem ser todos minúsculos
• Usar maiúsculas apropriadas (Pascal) para nomes e parâmetros de cmdlet

Cabeçalhos

• Comece com H1 primeiro - apenas um H1 por artigo
• Use apenas Cabeçalhos ATX
• Use maiúsculas e minúsculas para todos os cabeçalhos
• Não pule os níveis - sem H3 sem H2
• Limitar a profundidade do cabeçalho a H3 ou H4
• Adicionar linhas em branco antes e depois
• Não adicione ou remova cabeçalhos – o PlatyPS impõe cabeçalhos específicos em seu esquema

Blocos de códigos

• Adicionar linhas em branco antes e depois
• Usar limites de código marcados - powershell, Saída ou outro ID de linguagem apropriado
• Usar delimitador de código não marcado para blocos de sintaxe
• Coloque a saída em um bloco de código separado, exceto por exemplos básicos em que você não pretende que o leitor use o botão Copiar
• Consulte a lista de idiomas com suporte

Listas

• Recuar corretamente
• Adicionar linhas em branco antes do primeiro item e depois do último item
• Use hífen (-) para marcadores, e não asterisco (*), para reduzir a confusão com ênfase.
• Usar 1. para todos os itens em uma lista numerada

Terminologia

• Usar PowerShell vs. Windows PowerShell
• Consulte Terminologia do Produto

Exemplos de referência de cmdlet

• Deve ter pelo menos um exemplo na referência de cmdlet

• Exemplos devem ser apenas código suficiente para demonstrar o uso

• Sintaxe do PowerShell

  • Usar nomes completos de cmdlets e parâmetros – sem aliases
  • Use nivelamento para parâmetros quando a linha de comando ficar muito longa
  • Evite usar backticks de continuação de linha - use somente quando necessário

• Remover ou simplificar o prompt do PowerShell (PS>), exceto quando necessário para o exemplo

• O exemplo de referência de cmdlet deve seguir o seguinte esquema do PlatyPS

  ### Example 1 - Descriptive title
  
  Zero or more short descriptive paragraphs explaining the context of the example followed by one or
  more code blocks. Recommend at least one and no more than two.
  
  ```powershell
  ... one or more PowerShell code statements ...
  ```
  
  ```Output
  Example output of the code above.
  ```
  
  Zero or more optional follow up paragraphs that explain the details of the code and output.
  

• não coloque parágrafos entre os blocos de código. Todo o conteúdo descritivo deve vir antes ou depois dos blocos de código.

Vinculação a outros documentos

• Ao vincular fora do conjunto de documentos ou entre referência de cmdlet e conceitual
  • Usar URLs relativas ao site ao vincular ao Microsoft Learn (remover https://learn.microsoft.com/en-us)
  • não inclua localidades em URLs nas propriedades da Microsoft (remova /en-us da URL)
  • Todas as URLs para sites externos devem usar HTTPS, a menos que isso não seja válido para o site de destino
• Ao estabelecer vínculos dentro do conjunto de documentos
  • Use o caminho de arquivo relativo (../folder/file.md)
• Todos os caminhos usam caracteres de barra (/)
• Os links de imagem devem ter texto alt exclusivo