Novedades en la experiencia de documentación de PowerShell

Esta entrada la escribió Jeff Sandquist, Director general del equipo de Azure Growth and Ecosystem.

Hoy se ha publicado la nueva experiencia de Azure PowerShell para docs.microsoft.com. Entre las mejoras aplicadas a esta experiencia se incluye el control de versiones de módulos, el resaltado de la sintaxis de código, una tabla de contenido por la que se puede navegar más fácilmente y la posibilidad de editar y mejorar documentos, entre muchas otras. Sabemos por los comentarios de los clientes que el contenido de PowerShell se ha mejorado y este es el siguiente paso en nuestro viaje para mejorar la calidad de nuestro contenido. Hemos empezado con Azure, pero en los próximos meses trasladaremos todo nuestro contenido de PowerShell a esta experiencia.

Referencias del módulo de PowerShell unificadas

Los documentos de referencia del módulo de PowerShell se han diseñado para proporcionar una experiencia unificada en todos los módulos de PowerShell de Microsoft. Esto incluye:

• Patrones de direcciones URL coherentes: si conoce el nombre de un módulo o de un cmdlet, conoce su dirección URL. El patrón de dirección URL que se usa en Docs esdocs.microsoft.com/powershell/module/{nombre-del-modulo}/{nombre-del-cmdlet}/. Para el cmdlet Get-AzureRMStorageAccount que se encuentra en el módulo AzureRM.Storage, la dirección URL sería: https://docs.microsoft.com/powershell/module/azurerm.storage/get-azurermstorageaccount
• Experiencia de usuario coherente: el formato de módulos, cmdlets y ejemplos es ahora el mismo en toda la experiencia de documentación de PowerShell.
• Contribuciones sencillas: los usuarios de PowerShell pueden agregar ejemplos de código o modificar los documentos de referencia si hacen clic en el botón Editar directamente en la página del documento.
• Compatibilidad con el control de versiones para versiones anteriores de PowerShell: para filtrar en una versión específica de Azure PowerShell, utilice nuestro selector de versiones en la página.

Control de versiones de PowerShell

Aunque ya hemos mencionado el control de versiones de un módulo específico, algunos módulos incluyen un grupo de otros módulos, cada uno con su propio esquema de control de versiones. Por ejemplo, los clientes descargan Azure PowerShell mediante PowerShellGet. En el pasado, los clientes tenían que descifrar manualmente qué versiones de los documentos se aplican a su instalación. Por ejemplo, al instalar Azure PowerShell 3.7, era necesario conocer la versión de cada módulo individual que AzureRM 3.7 incluía con AzureRM.Automation 2.7 y AzureRM.CognitiveServices v0.5.0 y buscar esos documentos.

Con nuestra nueva experiencia solo tiene que elegir una versión para filtrar los módulos correctos según lo que se ha instalado.

Tabla de contenido mejorada

Además de la referencia de cmdlet, hemos agregado contenido de información general, pasos de instalación, introducción y ejemplos. Como referencia de Azure, también hemos agrupados cmdlets basados en el servicio de Azure.

Filtre fácilmente a medida que escribe, desde la tabla de contenido

Puede filtrar fácilmente la tabla de contenido de la izquierda a medida que escribe para hacer corresponder cmdlets o servicios que coincidan con ese nombre.

Mejoras en la página de cmdlets

Coloración y formato mejorados

Los cmdlets de PowerShell ahora muestran colores y un formato agradables para una mejor legibilidad.

Mejoras en los parámetros

Aunque los parámetros antes se agrupaban previamente según fueran obligatorios u opcionales, la lista de parámetros estaba desordenada. Para solucionar este problema, se han agregado encabezados de sección para agrupar los parámetros obligatorios y los opcionales, así como se ha mejorado la coloración y el estilo de los nombres de parámetros.

Comportamiento mejorado para la función de copiar y pegar

Varios ejemplos de código de cmdlets de PowerShell están prefijados con el texto PS C:\>. Al hacer clic en el botón Copiar para el ejemplo de código, ahora se eliminará el prefijo PS C:\>, tal como se muestra en la captura de pantalla del Bloc de notas siguiente.

Comentarios de los usuarios

Esperamos que vea importantes mejoras con esta versión.