Escritura de ayuda para cmdlets de PowerShell
Los cmdlets de PowerShell pueden ser útiles, pero a menos que los temas de Ayuda expliquen claramente qué hace el cmdlet y cómo usarlo, es posible que no se utilice o, peor aún, que pueda frustrar a los usuarios. El formato de archivo de ayuda del cmdlet basado en XML mejora la coherencia, pero una gran ayuda requiere mucho más.
Si nunca ha escrito la Ayuda sobre cmdlets, revise las siguientes pautas. El esquema XML necesario para crear el tema de Ayuda del cmdlet se describe en la siguiente sección. Comience con la creación del archivo de ayuda del cmdlet. Ese tema incluye una descripción de los nodos XML de nivel superior.
Pautas de escritura para la ayuda de cmdlets
escribe bien
Nada reemplaza un tema bien escrito. Si no eres un escritor profesional, busca un escritor o editor que te ayude. Otra alternativa es copiar el texto de Ayuda en Microsoft Word y utilizar las revisiones gramaticales y ortográficas para mejorar su trabajo.
escribe simplemente
Utilice palabras y frases sencillas. Evite la jerga. Tenga en cuenta que muchos lectores sólo disponen de un diccionario de lengua extranjera y su tema de Ayuda.
Escribe consistentemente
La ayuda para cmdlets relacionados debe ser similar (por ejemplo, Get-Content y Set-Content). Utilice las descripciones estándar para parámetros estándar, como Force y InputObject. (Cópielos de la Ayuda para los cmdlets principales). Utilice términos estándar. Por ejemplo, utilice "parámetro", no "argumento", y utilice "cmdlet", no "comando" ni "command-let".
Comienza la sinopsis con un verbo.
El campo de sinopsis informa al usuario qué hace el cmdlet, no qué es ni cómo funciona. Los verbos crean una declaración basada en tareas que informa a los usuarios si este cmdlet cumple con sus requisitos. Utilice verbos simples como "obtener", "crear" y "cambiar". Evite "establecer", que pueden ser palabras vagas y sofisticadas como "modificar".
Centrarse en los objetos
La mayoría de los cmdlets "obtener" muestran algo, pero su función principal es obtener un objeto. En su Ayuda, céntrese en el objeto, para que los usuarios comprendan que la visualización predeterminada es una de muchas y que pueden usar los métodos y propiedades del objeto que recuperó 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, indíquelo en la descripción detallada.
Utilice sintaxis convencional
Utilice el formato estándar Backus-Naur, que es común para la ayuda de línea de comandos de Windows y UNIX.
Utilice tipos de Microsoft .NET para valores de parámetros
Los marcadores de posición para los valores de los parámetros (en la sintaxis y las descripciones de los 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 completas de parámetros
Las descripciones de los parámetros deben informar a los usuarios de dos cosas: qué hace el parámetro (su efecto) y qué deben escribir para los valores de los parámetros.
Escribe ejemplos prácticos.
Los ejemplos deberían mostrar cómo usar todos los parámetros, pero lo más importante es mostrar cómo usar el cmdlet en tareas del mundo real. Comience con un ejemplo simple y escriba ejemplos cada vez más complejos. En el ejemplo final, muestre cómo utilizar el cmdlet en una canalización.
Utilice el campo Notas
Utilice el campo Notas para explicar los conceptos que los usuarios necesitan para comprender el cmdlet. También puede utilizar notas para ayudar a los usuarios a evitar errores comunes. Evite las URL a medida que cambian. En su lugar, proporcione a los usuarios términos para buscar.
Prueba tu ayuda
Pruebe la Ayuda tal como prueba su código. Haga que sus amigos y colegas lean el contenido de su Ayuda y proporcionen comentarios. También puede solicitar comentarios de los grupos de noticias.
Ver también
- Cómo crear el archivo de ayuda del cmdlet
- Cómo agregar el nombre del cmdlet y la sinopsis a un tema de ayuda del cmdlet
- Cómo agregar la descripción detallada a un tema de ayuda de cmdlet
- Cómo agregar sintaxis a un tema de ayuda de cmdlet
- Cómo agregar parámetros a un tema de ayuda de cmdlet
- Cómo agregar tipos de entrada a un tema de ayuda de cmdlet
- Cómo agregar valores de retorno a un tema de ayuda de cmdlet
- Cómo agregar notas a un tema de ayuda de cmdlet
- Cómo agregar ejemplos a un tema de ayuda de cmdlet
- Cómo agregar vínculos relacionados a un tema de ayuda de cmdlet
- SDK de Windows PowerShell