Partilhar via

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/AAAA
    • Alterar a data em que há uma atualização significativa ou factual
      • Reorganizar o artigo
      • Correção de erros factuais
      • Adicionando novas informações
    • Não altere a data se a atualização for insignificante
      • Corrigir erros de digitação e formatação
  • title: cadeia única de 43-59 caracteres (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

  • Retroceder elementos de sintaxe que aparecem, embutidos, dentro de um parágrafo
    • Nomes de cmdlets Verb-Noun
    • Variável $counter
    • Exemplos sintáticos 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 propriedades ou de parâmetros
  • Use negrito para nomes de propriedades, nomes de parâmetros, nomes de classe, nomes de módulos, nomes de entidades, nomes de objetos ou tipos
    • O negrito é usado para marcação semântica, não ênfase
    • Texto em negrito - use asteriscos **
  • Itálico - utilize o 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 - utilize apenas espaços
  • Sem espaços no final das linhas
  • As palavras-chave e os operadores do PowerShell devem ser todos minúsculos
  • Usar caixa apropriada (Pascal) para nomes e parâmetros de cmdlet

Cabeçalhos

  • Comece com H1 primeiro - apenas um H1 por artigo
  • Utilize apenas cabeçalhos ATX
  • Utilize a capitalização padrão para todos os cabeçalhos
  • Não salte níveis - não há H3 sem um H2
  • Limitar a profundidade do cabeçalho a H3 ou H4
  • Adicionar linhas em branco antes e depois
  • Não adicionar ou remover cabeçalhos - PlatyPS impõe cabeçalhos específicos em seu esquema

Blocos de código

  • Adicionar linhas em branco antes e depois
  • Usar cercas de código marcadas - powershell, Saída ou outro ID de idioma apropriado
  • Usar cercas de código não marcadas para blocos de sintaxe
  • Coloque a saída em bloco de código separado, exceto para exemplos básicos em que você não pretende que o leitor use o botão Copiar
  • Consulte a lista de idiomas suportados

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
  • Uso 1. para todos os itens em uma lista numerada

Terminologia

Exemplos de referência de cmdlet

  • Deve incluir pelo menos um exemplo na referência do cmdlet

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

  • Sintaxe do PowerShell

    • Utilize nomes completos de cmdlets e parâmetros - sem abreviaturas
    • Utilize "splatting" para os parâmetros quando a linha de comando se tornar demasiado longa
    • Evite usar backticks de continuação de linha - use apenas quando necessário

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

  • O exemplo de referência do cmdlet deve seguir o seguinte esquema 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.

Ligação a outros documentos

  • Ao vincular fora do conjunto de documentos ou entre a referência de cmdlet e a referência conceitual
    • Utilize URLs relativas ao site ao ligar ao Microsoft Learn (remova https://learn.microsoft.com/en-us)
    • não incluir locais em URLs nos sites da Microsoft (remova /en-us da URL)
    • Todos os URLs para sites externos devem usar HTTPS, a menos que isso não seja válido para o site de destino
  • Ao criar links no conjunto de documentos
    • Use o caminho de arquivo relativo (../folder/file.md)
  • Todos os caminhos usam caracteres de barra inclinada (/)
  • Os links de imagem devem ter texto alternativo exclusivo
  • Last updated on