Annonce concernant l’unification de la documentation de référence .NET sur docs.microsoft.com

Cet article a été écrit par Jeff Sandquist, Directeur Général de la division Azure Growth and Ecosystem.

Il y a presque un an, nous avons testé la documentation de référence de .NET Core sur docs.microsoft.com. Aujourd’hui, nous avons le plaisir d’annoncer notre documentation de référence unifiée sur les API .NET. Que vous soyez développeur amateur ou développeur dans une start-up ou une grande entreprise, nous savons que votre productivité est une priorité. Dans cette optique, nous travaillons en étroite collaboration avec l’équipe de Xamarin pour normaliser la façon dont nous documentons, découvrons et explorons les API .NET chez Microsoft.

Toute la documentation .NET au même endroit

Auparavant, quand vous souhaitiez trouver un SDK basé sur .NET fourni par Microsoft, vous deviez lancer votre moteur de recherche préféré pour rechercher l’emplacement du téléchargement et la documentation sur les API correspondante, ce qui pouvait prendre du temps.

Afin de faciliter les recherches, nous prévoyons d’unifier tous les SDK compatibles .NET au même endroit : https://docs.microsoft.com/dotnet/api. Vous trouverez sur ce site la documentation de référence pour .NET Framework, .NET Core, .NET Standard et Xamarin, ainsi que la documentation pour nos packages NuGet Azure. Dans les mois à venir, d’autres SDK seront ajoutés à cette expérience.

Présentation du navigateur d’API

Notre objectif premier est d’apporter une expérience de type IntelliSense pour que vous puissiez faire des recherches dans toutes les API .NET à partir d’un navigateur web. Vous pouvez rechercher un espace de noms, une classe, une méthode ou une interface en tapant tout ou partie de son nom directement dans la page du navigateur d’API.

Si vous ne savez pas à quel SDK appartient un type, un membre ou un espace de noms spécifique, sélectionnez simplement Toutes les API dans le menu déroulant de délimitation des API et lancez une recherche dans tous les documents de référence disponibles. Vous pouvez également sélectionner un framework ou un SDK spécifique et sa version (par exemple, .NET Framework 4.7) pour limiter vos recherches à cet ensemble d’API.

L’expérience du navigateur d’API est également intégrée en haut de la table des matières pour les API basées sur .NET, ce qui vous permet de trouver rapidement n’importe quelle API où que vous soyez dans la documentation de référence :

Quand vous êtes dans un espace de noms spécifique, le navigateur d’API est délimité à la famille d’API qui sont liées entre elles. Ainsi, votre recherche retourne toujours les meilleurs résultats possibles en fonction de votre contexte.

Prise en charge de la gestion de versions

Vous n’avez plus à vous demander si un type a des membres disponibles dans une version spécifique du .NET Framework ou du package NuGet Stockage Azure. Il vous suffit de changer la version dans le contrôle du navigateur d’API pour que le contenu soit ajusté en conséquence :

Conçu dans l’esprit open source

Pour créer le navigateur d’API, nous avons utilisé des normes et des outils ouverts. À la base, nous avons mis à profit DocFX, la chaîne d’outils de génération de documentation ouverte, ainsi que l’application mdoc de Xamarin.

Toute notre documentation de référence managée est désormais générée automatiquement à partir de fichiers binaires qui sont livrés sur NuGet ou qui font partie des distributions de framework principales, comme .NET Framework ou .NET Core.

Notre infrastructure d’intégration continue nous permet d’avoir une documentation précise pour les dernières API qui peut désormais être publique et ouverte aux contributions dans les heures suivant la publication. Nous avons également standardisé toute la documentation sur les API .NET au format ECMAXML pour créer une représentation des API cohérente et complète quel que soit le SDK documenté. Par ailleurs, vous n’avez pas besoin de connaître les subtilités du format de fichier, car vous pouvez contribuer au contenu dans Markdown qui est intégré dans les documents générés automatiquement. Les contributions de la communauté pour la documentation de référence seront activées le mois prochain.

Focus sur le contenu

En plus des nouvelles expériences, nous avons optimisé le contenu de référence pour qu’il soit plus facile à découvrir et plus lisible. Nous avons également mis à jour la table des matières pour qu’elle reflète toujours l’espace de noms. Que vous parcouriez des informations sur un espace de noms, un type ou un membre, nous vous montrerons toujours uniquement l’espace de noms parent avec tous ses types enfants & leurs membres regroupés respectifs :

Cela signifie que les pages de référence sont désencombrées et présentent d’abord les informations les plus importantes, comme des vues d’ensemble et des exemples visibles au premier coup d’œil.

Vous trouverez également des exemples pertinents dès le départ, filtrés selon le langage de programmation de votre choix, ce qui vous évitera de devoir faire défiler le contenu jusqu’en bas de la page pour trouver ce qui vous intéresse.

Pilotage par les commentaires

Tout ceci n’est que le début de notre refonte de l’expérience associée à la documentation de référence. Nous aimerions recevoir vos commentaires sur la façon dont nous pouvons rendre notre documentation plus attrayante et plus utile pour vous aider à être opérationnel le plus rapidement possible. Rendez-vous sur notre site UserVoice et faites-nous savoir comment nous pouvons améliorer l’expérience du navigateur d’API. Vous pouvez également nous contacter sur Twitter (@docsmsft) pour obtenir rapidement des informations.