Presentación de docs.microsoft.com

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

Hoy anunciamos la versión preliminar del nuevo servicio de documentación, https://docs.microsoft.com, donde se muestra contenido de soporte técnico para los productos Enterprise Mobility.

¿Por qué docs.microsoft.com?

En resumen, porque el contenido es importante. Hemos entrevistado y encuestado a cientos de desarrolladores y profesionales de TI y hemos estudiado los comentarios recibidos a lo largo de los años a través de la web en UserVoice. Resultaba evidente que necesitábamos introducir un cambio y crear una experiencia web moderna para el contenido. Lo primero que hicimos fue evaluar nuestra infraestructura de contenido existente, TechNet y MSDN. Ambos sitios se basan en un precario código base de entre 10 y 15 años de antigüedad, con un sistema de publicación e implementación arcaico que no estaba diseñado para ejecutarse en la nube.

Nuestro objetivo no solo se centraba en la experiencia, sino en el contenido que creamos y la manera en que los usuarios lo consumen. Durante muchos años, los clientes nos han solicitado que superáramos las barreras del texto con contenidos a nivel de características y que les ayudáramos a implementar soluciones para sus problemas empresariales. Sabíamos que el contenido que proporcionábamos y la plataforma que creábamos debían facilitar a los clientes el proceso de aprendizaje e implementación de las soluciones.

Nos dimos cuenta de que, para ofrecer una experiencia global adecuada, debíamos empezar desde cero. De este esfuerzo nace https://docs.microsoft.com, una nueva esperanza para la documentación de Microsoft.

Nota: Esta versión preliminar del sitio web incluye contenido *solo* para la documentación de Enterprise Mobility (que consta de Advanced Threat Analytics, Azure Active Directory, Azure Remote App, Multi-factor Authentication, Azure Rights Management, Intune y Microsoft Identity Manager). En el futuro, a medida que la plataforma evolucione gracias a los comentarios de los usuarios, migraremos más documentación a esta experiencia.

Principales características

Empezaremos con una página de documentación de ejemplo que se muestra a continuación y presentaremos algunas de las nuevas características del sitio.

Documentation Example

Legibilidad

A fin de mejorar la legibilidad del contenido, hemos cambiado el sitio para establecer un ancho de contenido determinado. Los estudios de seguimiento de los ojos han demostrado que se puede mejorar la comprensión y la velocidad de lectura con un ancho de contenido determinado, ya que es difícil para el ojo seguir grandes fragmentos de texto de izquierda a derecha. Para mostrarlo en la práctica, a continuación se muestra un ejemplo de un artículo de Intune en docs.microsoft.com seguido por el mismo artículo en TechNet. También hemos aumentado el tamaño de fuente del panel de navegación izquierdo y del texto en sí, ya que así nos lo solicitaron los usuarios en UserVoice: Increase Font size (UserVoice: Aumentar tamaño de fuente).

Docs and TechNet comparison

Tiempo de lectura estimado

Otra 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 o evaluar el uso de una tecnología y es más probable que lean los artículos si saben cuánto tiempo deben dedicarle a su lectura. También hemos agregado la fecha al contenido para indicar lo reciente que es la información, en función de los comentarios UserVoice.

Estimated reading time

Navegación por el sitio y el contenido

De acuerdo con las entrevistas realizadas a los clientes y los comentarios de UserVoice, otra área que había que mejorar era la navegación por el sitio, la arquitectura de la información y la organización de contenido en función de los objetivos del usuario. Hemos refactorizado el contenido en agrupaciones lógicas organizadas en torno a la evaluación, la introducción, la planificación, la implementación, la administración o la solución de problemas de productos o servicios. Puede ver este contenido desglosado en el panel de navegación izquierdo y en las páginas de productos o servicios.

A continuación se muestra una captura de pantalla de la página principal de la documentación de Intune:

Intune documentation screenshot

En el panel de navegación izquierdo de los artículos se puede ver esta misma clasificación:

Left navigation

Reducción de la longitud de los artículos

Otra cuestión común en los comentarios era la longitud en ocasiones abrumadora del contenido y la dificultad para navegar y encontrar contenidos en los artículos extensos. Para solucionar esto, hemos desglosado muchos artículos largos en pasos lógicos más pequeños. Además, hemos proporcionado botones Siguiente y Anterior en la parte inferior de los artículos para desplazarse entre los pasos en un tutorial de varias partes como se muestra a continuación.

Back and Next buttons

Mientras que a muchos clientes les gusta la funcionalidad de tener tutoriales de varias partes, también hemos oído que algunos clientes quieren tener la posibilidad de combinar tutoriales de varios pasos en un único archivo PDF imprimible sin conexión. Todavía no hemos hecho esto, pero estará disponible pronto en la vista previa.

Diseño dinámico

Para generar una gran experiencia en dispositivos móviles, tabletas y equipos, tal como solicitaron los usuarios en UserVoice, hemos cambiado a un diseño dinámico. Al hacer clic en el botón Opciones, es posible expandir o contraer para mostrar las mismas opciones en una vista de escritorio.

Responsive Page Design

Contribuciones de la comunidad

Toda la documentación incluida en docs.microsoft.com es de código abierto y está diseñada para permitir las contribuciones por parte de la comunidad. Esto sigue la iniciativa de otros equipos de Microsoft que han hecho que toda su documentación o algunas partes sean de código abierto, incluido ASP.NET, Azure, .NET Core y Microsoft Graph.

Todos los artículos tienen un botón Editar (se muestra a continuación) que lleva al archivo Markdown de código fuente de GitHub, donde se puede enviar fácilmente una solicitud de extracción para corregir o mejorar el contenido.

Mecanismos para enviar comentarios

Las preguntas, los comentarios y las opiniones de los usuarios son importantes para nosotros. Nos hemos asociado con Livefyre para proporcionar comentarios y Sidenotes (notas al margen) en todos los artículos. En la parte superior de cada artículo verá un vínculo de comentarios, como se muestra a continuación.

Comments link

Al hacer clic en el vínculo de comentarios irá a la parte inferior de la página, donde puede iniciar sesión (con sus credenciales de Twitter, Facebook, Google, Yahoo o Microsoft) para agregar, seguir o hacer clic en Me gusta en los comentarios.

Comments at bottom

También puede agregar Sidenotes o notas en cada párrafo de contenido o texto resaltado específicamente. Para ello, con el cursor del mouse en el símbolo de comentario de la derecha, haga clic en él para agregar un comentario incorporado.

Sidenote example

Uso compartido en las redes sociales

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

Sharing to Twitter and Facebook

También puede usar el cursor del mouse para seleccionar el contenido de un artículo y agregar un comentario o para compartir en Twitter o Facebook directamente desde el menú contextual, como se muestra a continuación.

Select and comment or share content

Direcciones URL descriptivas

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.

Temas del sitio web

También hemos agregado a los artículos un selector de temas para que sea posible cambiar entre un tema oscuro y un tema claro, algo que algunos usuarios habían solicitado en UserVoice.

Light and Dark Theme Selector

La imagen que se muestra a continuación muestra la diferencia entre el tema claro y el oscuro.

Light and Dark themes

Aspectos básicos

Muchos usuarios nos solicitaron a través de UserVoice que mejorásemos algunos aspectos básicos como el rendimiento del sitio. El tiempo de carga de la página en docs.microsoft.com es entre un 50-300 % más rápido y la distribución geográfica es mejor que nunca. Además, nos basamos en una arquitectura que se ejecuta al completo en Azure.

Envíenos sus comentarios

Esperamos que disfrute de la versión preliminar de docs.microsoft.com y que nos envíe sus comentarios a https://aka.ms/sitefeedback. En futuras publicaciones analizaremos los planes para mejorar drásticamente la experiencia del contenido de referencia y los planes para la localización de contenidos.