Actualización de noviembre de docs.microsoft.com

Artículo
09/15/2023

El autor de este artículo es Jeff Sandquist, director general de la división de Cloud + Enterprise.

Nos complace anunciar que hoy hemos migrado la documentación de Azure, Visual Studio 2017 RC, C++, ASP.NET Core, Entity Framework Core y SQL en Linux a docs.microsoft.com.

Ahora que hemos reunido todo el contenido, aumentará la coherencia de la experiencia de los clientes en lo que se refiere a la compatibilidad móvil, la localización, los comentarios, el uso compartido en las redes sociales y las contribuciones de la comunidad.

Aunque se trata de un lanzamiento importante, seguiremos actualizando el contenido y las características del sitio con frecuencia, por lo que no dude en enviarnos comentarios a través de UserVoice sobre su experiencia con el contenido.

También agregaremos contenido para Dynamics 365, Windows Server, SQL Server, System Center y escritorio de Windows durante los próximos meses.

En esta entrada

Principales características de Docs
Nuevas características de Docs
Documentación de Azure
Documentación de Visual Studio 2017 RC
Documentación de C++
Documentación de ASP.NET Core
Documentación de Entity Framework Core
Documentación de SQL en Linux

Principales características de Docs

Para aquellos que no estén familiarizados con docs.microsoft.com, estas son algunas de las características clave de la nueva experiencia.

Tiempo de lectura estimado y última actualización

Una sencilla mejora que hemos introducido en función de los comentarios recibidos consiste en proporcionar el tiempo de lectura estimado de un artículo. Sabemos que muchos usuarios solo disponen de unos pocos minutos entre reuniones para aprender y evaluar el uso de las tecnologías, y es más probable que lean los artículos si saben cuánto tiempo deben dedicarle a su lectura.

También hemos agregado marcas de tiempo al contenido para que los clientes puedan saber si es reciente. De este modo, no es necesario adivinar cuándo fue la última vez que se actualizó un artículo.

Diseño dinámico

Para generar una gran experiencia en dispositivos móviles, tabletas y equipos, hemos implementado un diseño dinámico. Al hacer clic en el botón Opciones situado en la parte superior de la página en dispositivos de pantalla pequeña, podrá acceder a las mismas opciones que se verían en un explorador de escritorio.

Documentación de alcance global

Hemos recibido numerosos comentarios de clientes de todo el mundo sobre la importancia del contenido localizado. Ahora, docs.microsoft.com está disponible en 45 idiomas, incluidos los que se escriben de derecha a izquierda (como el árabe y el hebreo), así como 63 configuraciones regionales en total para el contenido de Dynamics 365 con lógica de retroceso, en el caso de que no haya documentos localizados disponibles. Esto hace que los documentos tengan un alcance verdaderamente global y que estén listos para el contenido adicional que se agregará el año que viene.

Notas al margen y comentarios

Las preguntas, los comentarios y las opiniones de los usuarios son importantes para nosotros. Nos hemos asociado con Livefyre para proporcionar comentarios y notas al margen en todos los artículos. En la parte superior de cada artículo, verá una opción para ir directamente a la sección de comentarios.

Nos interesa conocer su opinión, por eso nos comprometemos a supervisar todos los comentarios y preguntas que incluya en las páginas de Docs y a darles respuesta.

Para realizar comentarios, puede iniciar sesión con sus credenciales de Twitter, Facebook, Google, Yahoo o Microsoft.

Además, podrá seguir las conversaciones de las que quiera realizar un seguimiento para mantenerse al tanto cuando le responda uno de los miembros del equipo o de la comunidad.

También puede agregar notas al margen en cada párrafo de contenido o texto resaltado específicamente. Para ello, seleccione un fragmento de texto con el cursor o haga clic en el icono de comentario que aparece a la derecha del párrafo al mantener el puntero sobre él.

El botón de uso compartido incluido en la parte superior de la página permite compartir contenido fácilmente con sus seguidores de Twitter y sus amigos de Facebook.

También puede seleccionar el contenido directamente con el mouse para compartirlo a través del widget contextual.

Temas claro y oscuro

También hemos agregado un selector de temas para que pueda cambiar entre un tema claro y un tema oscuro, algo que algunos de ustedes tienen [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme).

Direcciones URL fáciles de usar

Nos importa mucho la experiencia web, y algo que nos incomodaba habitualmente como usuarios de TechNet y MSDN era que los artículos no tenían direcciones URL legibles y fácil de usar. A continuación se muestra un ejemplo del mismo artículo con las nuevas direcciones URL.

Antes del

https://technet.microsoft.com/library/dn646983.aspx3

Después

https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune

Contribuciones de la comunidad

La mayoría de los documentos del sitio están habilitados para recibir contribuciones de la comunidad. Basta con hacer clic en el botón Editar del menú superior derecho para ir a la página de GitHub correspondiente, bifurcar el repositorio, realizar un cambio y enviar la solicitud de incorporación de cambios. Agradecemos las modificaciones en el contenido localizado y los comentarios sobre la experiencia general de contribución.

Nuevas características de Docs

Aunque muchas de estas características ya estaban presentes desde el día del lanzamiento del mes de mayo, hemos agregado una serie de características nuevas que se describen a continuación.

Filtro de la tabla de contenido en tiempo real

Hemos habilitado la tabla de contenido para que se pueda filtrar de forma instantánea. Esto significa que puede escribir unos pocos caracteres para filtrar el texto coincidente de manera que encuentre fácilmente el contenido que busca.

Otra característica clave que hemos agregado resuelve el problema del contenido de varios sitios. Si un artículo trata sobre cómo implementar una aplicación ASP.NET en Azure App Service, ¿debe aparecer en Azure o en ASP.NET? La respuesta es en ambos, pero sin duplicar el contenido en las dos secciones de los sitios por motivos de detectabilidad y coherencia.

Para ello, permitimos que los equipos de contenido seleccionen cualquier contenido de Docs y creen una vista de dicho contenido para los clientes. En la imagen siguiente se muestra un diseño hipotético para los desarrolladores de .NET que usan Docker, que pueden tener contenido distribuido desde los equipos de Azure, ASP.NET, .NET Core y Azure SDK de Visual Studio, todo ello en una sola vista.

Ejemplos de código comprobables

Uno de los aspectos más frustrantes de la documentación es el hecho de que los ejemplos presentados o vinculados no funcionen realmente en la máquina. En Microsoft, tenemos miles de ejemplos y fragmentos de código, y queremos asegurarnos de que los clientes tengan la garantía de que los ejemplos funcionan en las plataformas y las configuraciones admitidas.

Para ello, hemos desarrollado un sistema de integración continua (CI) extensible. De este modo, nos aseguramos de que los ejemplos compilen y generen la salida esperada para un conjunto determinado de cadenas de herramientas y sistemas operativos. Mientras trabajamos para incorporar más equipos, queremos garantizar que los usuarios que descarguen nuestro código tengan la seguridad de que se superarán todas las comprobaciones de calidad necesarias.

Contenido de referencia integrado

Hemos rediseñado el motor DocFX subyacente, el componente de código abierto que potencia docs.microsoft.com, para que incluya los enlaces de lenguaje para diferentes plataformas y formatos. Esto incluye la compatibilidad para:

CLI de Azure (Python)
PowerShell
.NET y .NET Core
Java
API de REST y Swagger

Esto conlleva para los clientes que la documentación ya no se desplaza sin sincronizar con funciones de API, ya que ahora hay un origen de verdad que controla los documentos y el código. Puede obtener más información sobre la compatibilidad específica con la referencia de API en las siguientes secciones sobre Azure y ASP.NET/EF.

Compatibilidad con PDF

Otra característica importante que los clientes han solicitado es la compatibilidad con PDF, es decir, poder descargar un conjunto específico de documentos sin que ocupen numerosos gigabytes y llevarlos consigo a cualquier lugar, tanto si se usa un dispositivo móvil como de escritorio.

Así pues, hemos activado la compatibilidad con PDF en la tabla de contenido. Nos hemos asegurado de que el archivo PDF se actualice a la vez que lo haga el contenido del sitio activo, de modo que siempre obtenga el contenido más reciente y de mejor calidad.

<img alt="screenshot16]()

Documentación de Azure

Hemos recibido comentarios sobre la fragmentación y los desafíos que supone la experiencia, por lo que vamos bien encaminados en el proceso para migrar la documentación técnica de Azure de azure.microsoft.com, MSDN y GitHub y consolidarla en https://docs.microsoft.com/azure/.

Nueva página de concentrador de Azure

También hemos aprovechado la oportunidad para cambiar la apariencia de la página de aterrizaje del contenido de Azure. Entre los puntos destacados se incluyen los siguientes:

Una pestaña Servicios que muestra los servicios de Azure agrupados por categoría.
Una pestaña Desarrollador que muestra todo el contenido de referencia de Azure para la API de REST, Azure SDK para .NET, Azure SDK para Java, CLI de Azure y Azure PowerShell.
Una pestaña Arquitectura para que los arquitectos y los desarrolladores obtengan información sobre los patrones de diseño a escala de nube.

Nueva página Servicio

Nos hemos asegurado de que las páginas de aterrizaje sean coherentes y vinculen a recursos clave, incluidos los siguientes:

Un vínculo Información general del servicio.
Varios tutoriales de introducción para todas las plataformas pertinentes y lenguajes de programación.
Un vínculo a todos los tutoriales de vídeo de un servicio determinado.
Vínculos a contenido de la referencia de API.
Un vínculo para descargar toda la documentación de ese servicio.

Nueva tabla de contenido

Al trasladarnos a docs.microsoft.com/azure, vamos a aprovechar la oportunidad para mejorar la coherencia de la navegación por la tabla de contenido. Aunque cada servicio tiene características únicas, la navegación por el sitio será similar.

Coloración mejorada

Hemos agregado coloración a las palabras clave y los parámetros en los ejemplos de código que representan la interfaz de la línea de comandos (CLI) de Azure. De este modo, le resultará más sencillo leer y entender el código.

Mejoras en las referencias

Uno de los principales problemas que los usuarios nos han comentado es que el contenido de la API, la línea de comandos y PowerShell nunca está actualizado. Debido a la rapidez con la que cambia Azure, los flujos de trabajo manuales heredados no funcionan.

En esta versión, hemos cambiado los sistemas para crear referencias directamente desde el código fuente. Cuando se publiquen compilaciones nuevas, también se publicará el contenido nuevo. Y, así como podía contribuir al contenido de procedimientos, podrá hacer lo mismo en la parte generada automáticamente de la documentación.

También estamos estandarizando el uso de la especificación de API abierta (antes denominada Swagger) para describir las API de REST, lo que ahora nos proporcionará una representación de datos coherente para los servicios REST que se puede usar para la documentación y los SDK de cliente. En el futuro, también podremos agregar características interactivas a la documentación de REST y ejemplos de cargas de solicitud-respuesta.

Para esta versión, hemos habilitado lo siguiente:

Documentación de Visual Studio 2017 RC

Hemos introducido toda la documentación de Visual Studio y la hemos integrado directamente en la nueva experiencia actualizada de docs.microsoft.com.

Nueva página de concentrador de Visual Studio

La página del concentrador de Visual Studio incluye vínculos clave para empezar a trabajar con la versión candidata para el lanzamiento de Visual Studio 2017.

Esto incluye los tutoriales de la Guía de instalación, Novedades e Introducción. Próximamente se incluirá contenido localizado. Habrá disponible contenido nuevo sobre temas como la refactorización, el trabajo con código que no está incluido en un proyecto, la depuración de problemas de rendimiento, sugerencias para optimizar el tiempo de inicio de Visual Studio, detalles sobre las nuevas características de productividad y navegación por el código en el editor y mucho más.

Ahora que Visual Studio admite un proceso de instalación completamente personalizable en el que solo recibe los componentes que quiere usar, puede obtener más información sobre como funciona esto en cada proyecto de desarrollo, independientemente de si las cargas de trabajo implican plataformas ASP.NET, Azure, Python o Windows.

Documentación de ASP.NET y Entity Framework Core

La documentación de ASP.NET Core y Entity Framework Core también se ha migrado de docs.asp.net y de GitHub respectivamente.

Referencia de ASP.NET y Entity Framework

Dado que ASP.NET Core y Entity Framework Core son proyectos de código abierto, hemos integrado totalmente su código fuente y sus comentarios de barra diagonal triple para crear la documentación de referencia de API correspondiente. Esto significa que la API y la documentación siempre estarán sincronizadas de forma automática.

Documentación de C++

En respuesta a las solicitudes que llevamos recibiendo desde hace tiempo de los clientes, hemos refactorizado la referencia de C++ en un formato más compacto que requiere menos vínculos entre los temas. Ahora, puede encontrar todos los documentos relativos a los miembros de clase en el mismo tema que la clase.

Además de todo esto, obtenga más información sobre los cambios más recientes en relación con el cumplimiento de estándares de C++ y las nuevas opciones de compilación como /fastlink, use la nueva guía de portabilidad para actualizar el código a partir de versiones anteriores de Visual Studio y descubra cómo probar la nueva compatibilidad para compilar en sistemas Linux con gcc.

Documentación de SQL en Linux

Ya puede probar SQL Server en Linux, que forma parte de SQL Server vNext Customer Technical Preview 1. La página del concentrador incluye vínculos clave que le llevan de una introducción a la administración y el desarrollo con SQL Server en Linux. Próximamente se incluirá contenido localizado.

Conclusiones

Esperamos poder ofrecer todavía más características en el nuevo sitio de documentación y garantizar una experiencia coherente con nuestros productos y servicios. Como usted, el usuario, es la parte más crítica del proceso de documentación, le animamos a ponerse en contacto con nosotros y enviar comentarios sobre cómo podemos mejorar esta experiencia en Twitter.

Actualización de noviembre de docs.microsoft.com

En esta entrada

Principales características de Docs