Compartir a través de

Escritura de la ayuda de los cmdlets de PowerShell

Los cmdlets de PowerShell pueden ser útiles, pero a menos que los temas de ayuda expliquen claramente lo que hace el cmdlet y cómo usarlo, es posible que el cmdlet no se use o, incluso peor, podría frustrar a los usuarios. El formato de archivo de ayuda del cmdlet basado en XML mejora la coherencia, pero la gran ayuda requiere mucho más.

Si nunca ha escrito la Ayuda del cmdlet, revise las instrucciones siguientes. El esquema XML necesario para crear el tema de ayuda del cmdlet se describe en la sección siguiente. Comience con Crear el archivo de ayuda del cmdlet. Este tema incluye una descripción de los nodos XML de nivel superior.

Directrices de escritura para la Ayuda de cmdlets

Escribir bien

Nada reemplaza un tema bien escrito. Si no es un escritor profesional, busque un escritor o editor para ayudarle. Otra alternativa es copiar el texto de ayuda en Microsoft Word y usar las comprobaciones gramaticales y ortográficas para mejorar el trabajo.

Escribir simplemente

Use palabras y frases simples. Evite la jerga. Tenga en cuenta que muchos lectores solo están equipados con un diccionario de idioma extranjero y su tema de Ayuda.

Escritura coherente

La ayuda para cmdlets relacionados debe ser similar (por ejemplo, Get-Content y Set-Content). Use las descripciones estándar para los parámetros estándar, como Force y InputObject. (Cópielos de la Ayuda para los cmdlets principales). Use términos estándar. Por ejemplo, use "parameter", no "argument" y use "cmdlet" no "command" o "command-let".

Inicio de la synopsis con un verbo

El campo synopsis informa al usuario de lo que hace el cmdlet, no lo que es o cómo funciona. Los verbos crean una instrucción basada en tareas que informa a los usuarios si este cmdlet cumple sus requisitos. Use verbos simples como "get", "create" y "change". Evite "set", que puede ser palabras vagas y sofisticadas como "modificar".

Centrarse en objetos

La mayoría de los cmdlets "get" muestran algo, pero su función principal es obtener un objeto . En la Ayuda, céntrese en el objeto para que los usuarios comprendan que la pantalla predeterminada es una de muchas y que pueden usar los métodos y propiedades del objeto que recuperó para ellos de diferentes maneras.

Escribir descripciones detalladas

Enumere brevemente todo lo que el cmdlet puede hacer en la descripción detallada. Si la función principal es cambiar una propiedad, pero el cmdlet puede cambiar todas las propiedades, enumere esta información en la descripción detallada.

Uso de la sintaxis convencional

Use el formato estándar Backus-Naur que es común para la Ayuda de la línea de comandos de Windows y Unix.

Uso de tipos de Microsoft .NET para los valores de parámetro

Los marcadores de posición de los valores de parámetro (en la sintaxis y las descripciones de parámetros) muestran los tipos de .NET Framework de los objetos que aceptará el parámetro. El equipo de PowerShell desarrolló esta convención para ayudar a enseñar a los usuarios sobre .NET Framework.

Escribir descripciones de parámetros completas

Las descripciones de parámetros deben informar a los usuarios de dos cosas: lo que hace el parámetro (su efecto) y lo que deben escribir para los valores de parámetro.

Escribir ejemplos prácticos

Los ejemplos deben mostrar cómo usar todos los parámetros, pero lo más importante es mostrar cómo usar el cmdlet en tareas reales. Comience con un ejemplo sencillo y escriba ejemplos cada vez más complejos. En el ejemplo final, se muestra cómo usar el cmdlet en una canalización.

Usar el campo Notas

Use el campo Notas para explicar los conceptos que los usuarios necesitan para comprender el cmdlet. También puede usar notas para ayudar a los usuarios a evitar errores comunes. Evite las direcciones URL a medida que cambien. En su lugar, proporcione los términos de los usuarios para buscar.

Prueba de la ayuda

Pruebe la Ayuda como si probara el código. Haga que amigos y compañeros lean su contenido de Ayuda y proporcionen comentarios. También puede solicitar comentarios de grupos de noticias.

Véase también