Partilhar via

Escrevendo ajuda para cmdlets do PowerShell

Os cmdlets do PowerShell podem ser úteis, mas a menos que seus tópicos da Ajuda expliquem claramente o que o cmdlet faz e como usá-lo, o cmdlet pode não ser usado ou, pior ainda, pode frustrar os usuários. O formato de arquivo de Ajuda do cmdlet baseado em XML melhora a consistência, mas uma grande ajuda requer muito mais.

Se você nunca escreveu a Ajuda do cmdlet, revise as diretrizes a seguir. O esquema XML necessário para criar o tópico da Ajuda do cmdlet é descrito na seção a seguir. Comece com Criando o arquivo de ajuda do cmdlet. Esse tópico inclui uma descrição dos nós XML de nível superior.

Escrevendo diretrizes para a Ajuda do cmdlet

Escreva bem

Nada substitui um tema bem escrito. Se você não é um escritor profissional, encontre um escritor ou editor para ajudá-lo. Outra alternativa é copiar o texto da Ajuda para o Microsoft Word e usar as verificações gramaticais e ortográficas para melhorar seu trabalho.

Escreva de forma simples

Use palavras e frases simples. Evite jargões. Considere que muitos leitores estão equipados apenas com um dicionário de língua estrangeira e o seu tópico da Ajuda.

Escreva de forma consistente

A ajuda para cmdlets relacionados deve ser semelhante (por exemplo, Get-Content e Set-Content). Use as descrições padrão para parâmetros padrão, como Force e InputObject. (Copie-os da Ajuda para os cmdlets principais.) Utilize condições-gerais. Por exemplo, use "parameter", não "argument" e use "cmdlet" e não "command" ou "command-let".

Iniciar a sinopse com um verbo

O campo de sinopse informa ao usuário o que o cmdlet faz, não o que é ou como funciona. Os verbos criam uma instrução baseada em tarefa que informa aos usuários se esse cmdlet atende aos seus requisitos. Use verbos simples como "obter", "criar" e "mudar". Evite "definir", que pode ser palavras vagas e extravagantes como "modificar".

Foco em objetos

A maioria dos cmdlets "get" exibe algo, mas sua função principal é obter um objeto. Na Ajuda, concentre-se no objeto, para que os usuários entendam que a exibição padrão é uma entre muitas e que eles possam usar os métodos e as propriedades do objeto que você recuperou para eles de maneiras diferentes.

Escreva descrições detalhadas

Liste brevemente tudo o que o cmdlet pode fazer na descrição detalhada. Se a função principal for alterar uma propriedade, mas o cmdlet puder alterar todas as propriedades, liste isso na descrição detalhada.

Usar sintaxe convencional

Use o formato Backus-Naur padrão que é comum para a Ajuda de linha de comando do Windows e Unix.

Usar tipos do Microsoft .NET para valores de parâmetro

Os espaços reservados para valores de parâmetro (nas descrições de sintaxe e parâmetro) mostram os tipos do .NET Framework dos objetos que o parâmetro aceitará. A equipe do PowerShell desenvolveu essa convenção para ajudar a ensinar os usuários sobre o .NET Framework.

Escrever descrições completas dos parâmetros

As descrições dos parâmetros devem informar os usuários de duas coisas: o que o parâmetro faz (seu efeito) e o que eles devem digitar para os valores dos parâmetros.

Escreva exemplos práticos

Os exemplos devem mostrar como usar todos os parâmetros, mas o mais importante é mostrar como usar o cmdlet em tarefas do mundo real. Comece com um exemplo simples e escreva exemplos cada vez mais complexos. No exemplo final, mostre como usar o cmdlet em um pipeline.

Utilizar o campo Notas

Use o campo Notes para explicar os conceitos que os usuários precisam para entender o cmdlet. Você também pode usar anotações para ajudar os usuários a evitar erros comuns. Evite URLs à medida que mudam. Em vez disso, forneça aos usuários termos para pesquisar.

Teste a sua Ajuda

Teste a Ajuda da mesma forma que você testa seu código. Peça aos amigos e colegas que leiam o conteúdo da Ajuda e forneçam comentários. Você também pode solicitar feedback de grupos de notícias.

Ver também

  • Last updated on