Compartilhar via

Escrever tópicos de ajuda para cmdlets do PowerShell

Os cmdlets do PowerShell podem ser úteis, mas a menos que os 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, examine 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.

Diretrizes de gravação para a Ajuda do Cmdlet

Escrever bem

Nada substitui um tópico bem escrito. Se você não for 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.

Escrever simplesmente

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

Gravar consistentemente

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.) Use termos padrão. Por exemplo, use "parâmetro", não "argumento" 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 ele é ou como ele 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 "get", "create" e "change". Evite "set", que pode ser palavras vagas e sofisticadas, como "modificar".

Foco em objetos

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

Escrever 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-a na descrição detalhada.

Usar sintaxe convencional

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

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

Os espaços reservados para valores de parâmetro (na sintaxe e descrições de 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.

Gravar descrições de parâmetros completas

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

Escrever 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.

Usar o campo Anotações

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

Testar sua ajuda

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

Consulte Também

  • Last updated on