Presentación de documentos de .NET Core
El autor de este artículo es Jeff Sandquist, director general de la división de Cloud + Enterprise.
Hoy lanzamos una versión preliminar de la documentación de .NET en docs.microsoft.com. Para obtener más información sobre las nuevas mejoras de la experiencia de documentación que ofrece docs.microsoft.com, consulte la entrada del blog de introducción a docs.microsoft.com. Además de ofrecer todas las características colaborativas, contenido de código abierto y direcciones URL más fáciles de usar en la plataforma docs.microsoft.com, hemos introducido algunas características nuevas específicas para los desarrolladores de .NET. En esta publicación destacaremos estas características nuevas y resumiremos nuestros planes para el futuro.
Aspectos destacados de la experiencia de documentación de .NET
Para acompañar a la interesante versión de RTM de .NET Core, la publicaremos en una posición destacada de la página principal de documentación de .NET. Para complementar la versión de RTM de .NET Core con todo lo que necesita para empezar a trabajar rápidamente, hemos incluido vínculos a artículos y una nueva experiencia de referencia en la parte superior de la lista.
El ecosistema de .NET a su alcance
Verá vínculos para descargar las nuevas bibliotecas de .NET Core, ASP.NET, Entity Framework y Azure, usar Xamarin para compilar aplicaciones iOS con .NET, y compilar aplicaciones de la Plataforma universal de Windows (UWP) con .NET. Todavía no hemos trasladado todo el contenido de .NET a docs.microsoft.com, pero la página principal de documentación de .NET será el punto de partida para acceder a toda la documentación de .NET.
Artículos
Nuestros escritores e ingenieros, así como algunos miembros dedicados de la comunidad, han trabajado incansablemente para crear artículos relacionados con .NET Core que encontrará en la sección de documentación de .NET. Aquí encontrará diversos artículos, como:
Estos y muchos otros temas están incluidos en el tema de docs.microsoft.com, con una tabla de contenido clara en cada página, así como el tiempo estimado para leer cada artículo e información sobre las personas que han colaborado en el artículo.
Todos los artículos de .NET son de código abierto y están disponibles en GitHub en el repositorio de documentos del equipo de .NET. Si encuentra algún problema relacionado con la documentación o quiere mejorarla, basta con que haga clic en el botón Editar en el panel de navegación derecho de cada artículo.
Para editar un artículo, solo tiene que hacer clic en el botón Editar en cualquiera de los archivos Markdown del repositorio, agregar el contenido y enviar una solicitud de incorporación de cambios. Una vez que nuestro equipo revise y acepte la solicitud de incorporación de cambios, sus contribuciones se publicarán en el sitio en cuestión de minutos.
Referencia de API
Además del excelente contenido que crean nuestros escritores, ingenieros y apasionados miembros de la comunidad, hemos realizado mejoras significativas en la experiencia de referencia. La experiencia de referencia se ha rediseñado completamente en esta versión preliminar, siguiendo los mismos principios de diseño de los artículos docs.microsoft.com.
Al igual que esos artículos, las nuevas páginas de referencia son dinámicas, están diseñadas según principios web modernos y se ven mejor en los dispositivos móviles.
Hemos agregado una búsqueda de tipos a todas las páginas de espacio de nombres. Esto permite buscar fácilmente por nombre de tipo todos los tipos de .NET. Con cada pulsación de teclas, filtramos la lista de tipos que se muestran en el panel de navegación izquierdo. Esta interesante característica nueva del área de referencia está incluida en nuestro nuevo marco para generar documentación de referencia de .NET conocida como DocFX, un proyecto de código abierto en GitHub.
Cuando haga clic en tipos individuales en el panel de navegación izquierdo de cualquier espacio de nombres, irá directamente a la sección de introducción de la página del espacio de nombres de ese tipo. Al hacer clic en el nombre del tipo en el área principal del contenido de referencia, verá la página de detalles de la clase, que contiene la cadena de herencia de la clase, la declaración y los detalles de los miembros de propiedad y método de la clase.
Para cada miembro del método, verá los detalles de los parámetros y un resumen del método.
Principios de ingeniería e información
Además del desarrollo y la mejora continuos de las herramientas de generación de documentos DocFX, hemos realizado mejoras significativas en los principios de ingeniería y documentación que verá claramente en la nueva experiencia de documentación de .NET.
Mejora de la automatización
Cuando se reciben solicitudes de incorporación de cambios de posibles colaboradores, validamos que el colaborador haya seguido un proceso sencillo, consistente en firmar el contrato de licencia para colaboradores (este proceso es totalmente electrónico y tarda unos minutos en completarse). Si las aportaciones cumplen las directrices de contribución, las modificaciones pequeñas aparecerán publicadas en el sitio minutos después de que se acepten las solicitudes de incorporación de cambios.
Mejora de las direcciones URL
Un principio importante de la experiencia global de docs.microsoft.com es la optimización de las direcciones URL para mejorar la indexación de búsqueda y las estimaciones. Hemos mantenido este principio en la documentación de .NET. Tanto los artículos como la documentación de referencia tienen direcciones URL más claras. Veamos, por ejemplo, la dirección URL de MSDN clásica para el espacio de nombres System:
En la nueva documentación de referencia, la dirección URL es más lógica, legible y, lo que es más importante, más reconocible.
Creación más ágil y abierta
El contenido no solo es de código abierto, y no solo aceptamos contribuciones de la comunidad. Además, todo el contenido de docs.microsoft.com (incluida la documentación de .NET) está disponible bajo una licencia de Creative Commons. Puede leerlo, copiarlo, hacer referencia a él y volver a usar partes de él (incluso para uso comercial). Los escritores e ingenieros han trabajado en el nuevo sistema activamente con miembros de la comunidad durante meses. Ha sido una transición interesante y emocionante, y esto es solo el principio.
Planes de futuro
Esta sección de docs.microsoft.com, al igual que el resto del sitio, todavía se encuentra en versión preliminar, por lo que estamos abiertos a recibir comentarios constructivos. No dude en enviar sus ideas sobre características a UserVoice.
En las próximas semanas, publicaremos los comentarios XML que se usan para generar documentación de referencia directamente en el código fuente de .NET. Esto permitirá que cualquier usuario haga clic fácilmente para actualizar la documentación de referencia de .NET Framework.
También seguiremos retocando el diseño y la presentación de la referencia, así como la característica mencionada anteriormente para editar el contenido de la referencia.
Estamos encantados de presentarle la nueva área de documentación de .NET en docs.microsoft.com y esperamos mejorar su experiencia en el futuro.