Présentation de la documentation .NET Core
Cet article a été écrit par Jeff Sandquist, Directeur Général de la division Cloud + Enterprise.
Aujourd’hui, nous avons publié une préversion de la Documentation .NET sur docs.microsoft.com. Pour en savoir plus sur les nouvelles améliorations apportées à l’expérience de documentation offertes par docs.microsoft.com, consultez le billet de blog de présentation de docs.microsoft.com. En plus d’avoir toutes les fonctionnalités de collaboration, du contenu open source et des URL plus conviviales disponibles sur la plateforme docs.microsoft.com, nous avons introduit de nouvelles fonctionnalités spécifiques aux développeurs .NET. Ce billet passe en revue ces nouvelles fonctionnalités et résume nos plans pour l’avenir.
Principales caractéristiques de l’expérience de la Documentation .NET
Pour accompagner la captivante version RTM de .NET Core, nous la plaçons au centre de la page d’accueil de la Documentation .NET. Pour compléter la version RTM de .NET Core avec tout ce dont vous avez besoin pour commencer rapidement, nous avons placé des liens vers des articles et une nouvelle documentation de référence en haut de la liste.
L’écosystème .NET à portée de main
Vous verrez des liens permettant de télécharger les nouvelles bibliothèques .NET Core, ASP.NET, Entity Framework, Azure, d’utiliser Xamarin pour générer des applications iOS à l’aide de .NET et de générer des applications de plateforme Windows universelle (UWP) à l’aide de .NET. Nous n’avons pas encore déplacé tout le contenu .NET vers docs.microsoft.com, mais la page d’accueil de la Documentation .NET est votre point de départ pour accéder à toute la documentation .NET.
Articles
Nos rédacteurs et ingénieurs, ainsi que quelques membres dédiés de la communauté, ont travaillé sans relâche à la création de nouveaux articles relatifs à .NET Core que vous trouverez dans la section Documentation .NET. Vous trouverez ici une série d’articles tels que :
- Didacticiels .NET Core
- Déploiement d’applications .NET Core
- Effectuer des tests unitaires dans .NET Core
Ces rubriques et bien d’autres sont toutes présentées dans le thème docs.microsoft.com, avec une table des matières propre sur chaque page, ainsi qu’une estimation de la durée nécessaire pour lire chaque article et les informations relatives au contributeur pour chaque article.
Tous les articles .NET sont open source et disponibles sur GitHub dans le dépôt de la documentation de l’équipe .NET. Si vous rencontrez des problèmes dans la documentation ou si vous souhaitez l’améliorer, il suffit, pour cela, de cliquer sur le bouton Modifier du volet de navigation de droite de chaque article.
Pour modifier un article, il suffit de cliquer sur le bouton Modifier de n’importe lequel des fichiers Markdown présents dans le dépôt, d’ajouter votre contenu, puis de soumettre une demande de tirage (pull request). Une fois que l’une de nos équipes examine et accepte votre demande de tirage (pull request), vos contributions sont publiées sur le site en quelques minutes.
Référence API
En plus de l’excellent contenu créé par nos rédacteurs, ingénieurs et membres passionnés de la communauté, nous avons apporté des améliorations significatives à la documentation de référence. La documentation de référence a été entièrement repensée dans cette version préliminaire, en empruntant les mêmes principes de conception que ceux utilisés dans les articles docs.microsoft.com.
Comme ces articles, les nouvelles pages de la documentation de référence sont réactives, conçues avec des principes web modernes et s’affichent mieux sur les appareils mobiles.
Nous avons ajouté une recherche de type à toutes les pages d’espace de noms. Cela vous permet d’effectuer facilement des recherches par nom de type pour tous les types .NET. Chaque fois que vous appuyez sur une touche, nous filtrons la liste des types affichés dans le volet de navigation gauche. Cette nouvelle fonctionnalité très intéressante du domaine de la documentation de référence est incluse dans notre nouveau framework destiné à la génération de la documentation de référence .NET appelé DocFX, un projet open source sur GitHub.
Lorsque vous cliquerez sur des types individuels dans le volet de navigation de gauche de n’importe quel espace de noms, vous passerez directement à la section d’introduction de la page de l’espace de noms à ce type. En cliquant sur le nom du type dans la zone principale du contenu de référence, vous verrez la page des détails de la classe, qui contient la chaîne d’héritage de la classe, la déclaration et des détails sur les membres de propriété et de méthode de la classe.
Pour chaque membre de méthode, vous voyez des détails sur les paramètres et un résumé de la méthode.
Principes d’information et d’ingénierie
En plus du développement et de l’amélioration continue des outils de génération de documents DocFX, nous avons apporté des améliorations significatives aux principes d’ingénierie et de documentation qui vous apparaîtront clairement dans la nouvelle expérience de la Documentation .NET.
Meilleure automatisation
Lorsque des demandes de tirage (pull requests) sont reçues de contributeurs potentiels, nous vérifions que le contributeur a suivi un processus simple de signature de notre contrat de licence de contributeur. (Ce processus est entièrement électronique et prend quelques minutes.) Tant que les contributions respectent les Instructions relatives à la contribution, de petites modifications doivent apparaître en direct sur le site quelques minutes après l’acceptation des demandes de tirage (pull requests).
Meilleures URL
De meilleures URL visant à améliorer l’indexation de la recherche et la« tentative de deviner » constituent un principe important de l’expérience docs.microsoft.com globale. Nous avons conservé ce principe dans la Documentation .NET. Les articles et la documentation de référence ont des URL plus épurées. Prenez l’exemple de l’URL MSDN classique pour l’espace de noms System :
Dans la nouvelle documentation de référence, l’URL est plus logique, lisible par l’utilisateur et, plus important encore, plus détectable.
Création plus agile et plus ouverte
Le contenu n’est pas seulement open source et nous n’acceptons pas uniquement les contributions de la communauté. De plus, tout le contenu sur docs.microsoft.com (y compris la Documentation .NET) est entièrement disponible dans le cadre d’une licence Creative Commons. Vous pouvez le lire, le copier, le référencer et en réutiliser des parties (même pour une utilisation commerciale). Les rédacteurs et les ingénieurs travaillent activement avec des membres de la communauté depuis des mois dans le nouveau système. Cette phase de transition a été intéressante et captivante, et nous avons plus à proposer à l’avenir.
Plans pour l’avenir
Cette section de docs.microsoft.com, comme le reste du site, est toujours en préversion. Nous encourageons donc les commentaires et commentaires constructifs. Envoyez vos idées de fonctionnalités à UserVoice.
Dans les semaines à venir, nous publierons les commentaires XML qui sont utilisés pour générer la documentation de référence directement dans le code source .NET. Cela permettra à tout utilisateur de mettre à jour facilement la documentation de référence .NET Framework.
Nous continuerons également à affiner la conception et la disposition de la documentation de référence, ainsi que la possibilité susmentionnée de modifier le contenu de référence lui-même.
Nous sommes ravis de vous présenter le nouveau domaine Documentation .NET sur docs.microsoft.com, et nous sommes impatients d’améliorer votre expérience à l’avenir.