Presentación de una experiencia de referencia unificada de .NET en docs.microsoft.com
Esta entrada la escribió Jeff Sandquist, Director general del equipo de Azure Growth and Ecosystem.
Hace casi un año, empezamos a diseñar la documentación de referencia para .NET Core en docs.microsoft.com. Hoy tenemos el placer de anunciar nuestra experiencia de referencia de API de .NET unificada. Entendemos que la productividad de los desarrolladores es clave: desde un desarrollador aficionado hasta una startup o una empresa. Con esto en mente, establecimos una estrecha relación con el equipo de Xamarin para estandarizar la forma en que documentamos, descubrimos y navegamos por las API de .NET en Microsoft.
Toda la documentación de .NET: en un solo lugar
Anteriormente, si quería encontrar un SDK basado en .NET enviado por Microsoft, tenía que pasar algún tiempo con su motor de búsqueda favorito, tratando de encontrar el lugar donde podía descargarlo y descubrir la documentación pertinente de la API.
En el futuro, tenemos previsto contar con todos los SDK compatibles con .NET unificados y que se pueden buscar en un solo lugar: https://docs.microsoft.com/dotnet/api. Allí encontrará documentación de referencia para .NET Framework, .NET Core, .NET Standard y Xamarin, así como documentación de nuestros paquetes NuGet de Azure. En los próximos meses, agregaremos más SDK a esta experiencia.
Introducción al Explorador de API
Nuestro objetivo principal es aportar una experiencia de tipo IntelliSense para buscar todas las API de .NET desde un explorador web. Puede buscar un espacio de nombres, una clase, un método o una interfaz escribiendo su nombre completo o parcial directamente en la página Explorador de API.
Si no está seguro de a qué SDK pertenece un tipo, miembro o espacio de nombres específico, puede seleccionar simplemente Todas las API en el menú desplegable de ámbito de la API y buscar en todos los documentos de referencia disponibles. Por otra parte, si desea limitar su búsqueda, puede seleccionar un marco o SDK específico, así como su versión, por ejemplo, .NET Framework 4.7, y buscar solo en ese conjunto de API.
La experiencia del Explorador de API también se integra en la parte superior de la tabla de contenido de las API basadas en .NET, lo que le permite encontrar rápidamente cualquier API independientemente de dónde se encuentre dentro de la documentación de referencia:
Una vez que se encuentra en un espacio de nombres específico, el Explorador de API se limita a la familia de API que están conectadas entre sí, por lo que su búsqueda siempre devuelve los mejores resultados posibles basados en su contexto.
Compatibilidad de versiones
Ya no tiene que preguntarse si un tipo tiene miembros disponibles en una versión específica de .NET Framework o el paquete NuGet de Azure Storage; lo único que debe hacer es cambiar la versión desde el control Explorador de API y el contenido se ajustará en consecuencia:
Creación con el código abierto en mente
Para compilar el Explorador de API, hemos usado estándares y herramientas abiertos. En esencia, aprovechamos DocFX, la cadena de herramientas de generación de documentación abierta, junto con la aplicación mdoc de Xamarin.
Toda nuestra documentación de referencia administrada se genera ahora automáticamente a partir de los binarios que se distribuyen en NuGet o que forman parte de las principales distribuciones de marcos, como .NET Framework o .NET Core.
Nuestra infraestructura de integración continua nos permite tener documentación precisa para las API más recientes que ahora pueden ser públicas en cuestión de horas a partir del lanzamiento, abiertas a las contribuciones. También hemos estandarizado toda la documentación de la API de .NET en el formato ECMAXML, que crea una representación coherente y completa de la API independientemente del SDK que se documente. Además, no es necesario que conozca los entresijos del formato de los archivos, ya que puede contribuir con contenido en Markdown, insertado en los documentos generados automáticamente. Las contribuciones de la comunidad para la documentación de referencia se habilitarán en el próximo mes.
El foco en el contenido
Además de las nuevas experiencias, también hemos optimizado el contenido de referencia para que sea más fácil de encontrar y leer. Hemos actualizado la tabla de contenido para que siempre esté centrada en el espacio de nombres. Tanto si va a examinar información sobre un espacio de nombres, un tipo o un miembro, siempre le mostraremos solo el espacio de nombres primario con todos sus tipos secundarios & sus respectivos miembros agrupados:
Esto significa que las páginas de referencia se despejan y muestran primero la información más importante, como los resúmenes generales y los ejemplos, todo de un vistazo.
También verá ejemplos que son pertinentes para usted desde el principio, filtrados por el lenguaje de programación que prefiera; ya no tiene que desplazarse hasta la parte inferior de la página para encontrarlos.
Controlado por comentarios
Esto es solo el principio de la renovación de la experiencia de documentación de referencia. Queremos conocer su opinión sobre cómo podemos hacer que nuestra documentación sea más atractiva y útil y que le permita avanzar lo más rápidamente posible. Vaya a nuestro sitio UserVoice y háganos saber cómo podemos mejorar la experiencia del Explorador de API. También puede comunicarse con nosotros en Twitter @docsmsft, para obtener actualizaciones rápidas.