Mise à jour de novembre de docs.microsoft.com

  • Article

Cet article a été écrit par Jeff Sandquist, Directeur Général de la division Cloud + Enterprise.

Nous avons le plaisir de vous annoncer aujourd’hui la migration de la documentation d’Azure, Visual Studio 2017 RC, C++, ASP.NET Core, Entity Framework Core et SQL sur Linux vers docs.microsoft.com.

En regroupant tout notre contenu à un même endroit, nous permettons à nos clients de bénéficier d’une expérience cohérente pour la prise en charge mobile, la traduction, les commentaires, le partage sur les réseaux sociaux ou les contributions à la communauté.

Il s’agit d’une migration majeure, mais nous continuerons à mettre à jour le contenu et les fonctionnalités du site régulièrement. N’hésitez pas à nous envoyer vos commentaires UserVoice pour nous faire part de votre expérience du contenu.

Dans les mois à venir, nous ajouterons du contenu pour Dynamics 365, Windows Server, SQL Server, System Center et Windows.

Dans ce billet

  • Principales fonctionnalités de la documentation
  • Nouvelles fonctionnalités de la documentation
  • Documentation Azure
  • Documentation Visual Studio 2017 RC
  • Documentation C++
  • Documentation ASP.NET Core
  • Documentation Entity Framework Core
  • Documentation SQL sur Linux

Principales fonctionnalités de la documentation

Pour ceux d'entre vous qui ne connaissent pas docs.microsoft.com, voici quelques-unes des principales caractéristiques de notre nouvelle expérience.

Estimation du temps de lecture et date de dernière mise à jour

L’estimation du temps de lecture d’un article est l’une des améliorations simples que nous avons apportées suite à vos commentaires. Pour beaucoup d’entre vous, l’apprentissage et l’évaluation de nouvelles technologies se limitent à quelques minutes ici et là entre deux réunions. Vous êtes donc plus enclin à lire un article si vous savez à l’avance combien de temps il faut pour le lire.

Nous avons également ajouté des horodatages au contenu pour permettre aux clients de savoir de quand datent les articles : vous n’aurez plus à deviner la date de leur dernière mise à jour.

capture d’écran 1

Présentation interactive

L’expérience doit être conviviale sur appareil mobile, sur tablette et sur PC. Nous avons donc implémenté une présentation interactive. Un clic sur le bouton Options en haut d’une page sur un appareil à petit écran permet d’accéder aux mêmes options que celles affichées sur un navigateur de poste de travail.

capture d’écran 2

Documentation internationale

Les clients internationaux nous font régulièrement part de l’importance de la traduction du contenu. docs.Microsoft.com prend désormais en charge 45 langues, y compris celles qui se lisent de droite à gauche comme l’arabe et l’hébreu, ainsi que 63 paramètres régionaux au total pour le contenu Dynamics 365, avec une solution de secours quand les documents traduits ne sont pas disponibles. Notre documentation est véritablement internationale, prête à recevoir le contenu qui sera publié l’année prochaine.

capture d’écran 3capture d’écran 4

Annotations et commentaires

Vos questions, avis et commentaires nous intéressent ! Nous avons collaboré avec Livefyre pour ajouter des commentaires et des annotations à tous nos articles. En haut de chaque article figure une option permettant d’accéder directement à la section des commentaires.

Votre avis nous intéresse, et nous nous engageons à répondre à tous les commentaires et questions posées dans les pages de documentation.

capture d’écran 5

Pour insérer un commentaire, vous pouvez vous connecter avec vos informations d’identification Twitter, Facebook, Google, Yahoo ou Microsoft.

capture d’écran 6

De plus, vous pouvez suivre les threads là où vous attendez une réponse. Ainsi, vous savez toujours quand l’un des membres de notre équipe ou de la Communauté vous répond.

capture d’écran 7

Vous pouvez également ajouter des annotations à chaque paragraphe de contenu ou à une partie de texte sélectionnée. Pour ce faire, il vous suffit de sélectionner un segment de texte avec le curseur de la souris ou de cliquer sur l’icône de commentaire qui s’affiche sur le côté droit du paragraphe quand vous pointez dessus.

capture d’écran 8

Partage sur les réseaux sociaux

Le bouton de partage situé en haut de la page vous permet de partager facilement du contenu sur Twitter et avec vos amis Facebook.

capture d’écran 9

Vous pouvez également sélectionner du contenu directement avec votre souris pour le partager par le biais du widget contextuel.

capture d’écran 10

Thème clair / sombre

Nous avons également ajouté un sélecteur de thème afin que vous puissiez passer d’un thème clair à un thème sombre, ce que certains d’entre vous ont [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme).

capture d’écran 12

URL conviviales

L’expérience web est importante pour nous. Et en tant qu’utilisateurs de TechNet et de MSDN, le fait que les articles ne disposaient pas d’URL conviviales et lisibles était une source fréquente de frustration. Voici un exemple du même article avec nos nouvelles URL.

Avant

https://technet.microsoft.com/library/dn646983.aspx3

Après

https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune

Contributions de la communauté

La grande majorité des documents sur notre site sont compatibles avec les contributions de la Communauté. Il vous suffit de cliquer sur le bouton Modifier dans le menu en haut à droite pour accéder à la page GitHub correspondante, créer une branche dans le dépôt, apporter une modification et envoyer votre demande d’extraction. N’hésitez pas à modifier le contenu traduit et à nous faire part de vos commentaires sur l’expérience de contribution en général.

capture d’écran 13

Nouvelles fonctionnalités de la documentation

La plupart de ces fonctionnalités existent depuis la date de lancement en mai, mais nous en avons également ajouté quelques nouvelles, décrites ci-dessous.

Filtre de table des matières en temps réel

Vous pouvez désormais filtrer sur notre table des matières instantanément. Il vous suffit de taper quelques caractères pour obtenir le texte correspondant et trouver le contenu recherché.

capture d’écran 14

Table des matières avec navigation gauche

Une autre fonctionnalité clé que nous avons ajoutée résout le problème du contenu présent sur plusieurs sites. Un article sur le déploiement d’une application ASP.NET sur Azure App Service doit-il être répertorié sous Azure ou ASP.NET ? La réponse est sur les deux, mais sans dupliquer le contenu dans les deux sections du site pour des raisons de cohérence et de découvertibilité.

Pour ce faire, les équipes de contenu peuvent sélectionner n’importe quel contenu de la documentation et créer une vue de ce contenu pour les clients. L’illustration ci-dessous montre une disposition hypothétique pour des développeurs .NET utilisant Docker avec du contenu fourni par les équipes Azure, ASP.NET, .NET Core et Visual Studio Azure SDK, le tout dans une vue unique.

capture d’écran 15

Exemples de code vérifiables

L’une des caractéristiques les plus frustrantes de la documentation est lorsque les exemples présentés ou liés ne fonctionnent pas sur votre ordinateur. Chez Microsoft, nous avons des milliers d’exemples et d’extraits de code et nous souhaitons que nos clients soient sûrs que ces exemples fonctionnent sur les plateformes et les configurations prises en charge.

Pour ce faire, nous avons conçu un système d’intégration continue (CI, Continuous Integration) extensible pour garantir que les exemples se compilent et produisent le résultat attendu pour un ensemble défini de systèmes d’exploitation et de chaînes d’outils. Nous intégrons actuellement d’autres équipes à ce schéma et voulons nous assurer que les utilisateurs qui téléchargent notre code soient certains qu’il a passé tous les contrôles qualité nécessaires.

Contenu de référence intégré

Nous avons remanié le moteur DocFX sous-jacent, le composant open source à la base de docs.microsoft.com, pour inclure des liaisons de langage pour différentes plateformes et formats. Cela inclut la prise en charge des éléments suivants :

  • Interface de ligne de commande Azure (Python)
  • PowerShell
  • .NET et .NET Core
  • Java
  • API REST / Swagger

Pour les clients, cela signifie que la documentation ne doit plus dériver hors synchronisation par rapport aux fonctions API, car il y a maintenant une seule source de vérité qui gère les documents et le code. Pour en savoir plus sur la prise en charge spécifique de la référence d’API, consultez les sections sur Azure et ASP.NET/EF ci-dessous.

Prise en charge de PDF

Une autre fonctionnalité majeure demandée par les clients est la prise en charge du format PDF : vous pouvez télécharger un ensemble spécifique de documents sans avoir besoin de plusieurs gigaoctets d’espace libre, et l’emporter n’importe où avec vous, que vous utilisiez un appareil mobile ou un ordinateur de bureau.

Pour cela, nous avons activé la prise en charge de PDF dans notre table des matières. Nous nous assurons de mettre à jour le fichier PDF quand le contenu est mis à jour sur le site en ligne. Ainsi, vous obtenez toujours les versions les plus récentes de notre contenu.

<img alt="screenshot16]()

Documentation Azure

Nous avons bien reçu vos commentaires sur le contenu actuellement dispersé et les difficultés rencontrées au cours de votre expérience. Ne vous inquiétez pas, la migration de notre documentation technique sur Azure à partir d’azure.microsoft.com, de MSDN et de GitHub vers https://docs.microsoft.com/azure/.

Nouvelle page hub pour Azure

Nous en avons également profité pour modifier l’apparence de la page d’accueil du contenu Azure. Notez entre autres la présence des éléments suivants :

  • Un onglet Services qui répertorie les services Azure groupés par catégorie.
  • Un onglet Développeur qui répertorie tout le contenu de référence Azure pour l’API REST, Azure .NET SDK, Azure Java SDK, Azure CLI et Azure PowerShell.
  • Un onglet Architecture qui permet aux architectes et aux développeurs d’en savoir plus sur les modèles de conception à l’échelle du cloud.
capture d’écran 17

Nouvelle page Service

Nous avons fait en sorte que nos pages d’accueil soient cohérentes et mènent à des ressources clés, notamment :

  • Un lien Présentation du service.
  • Des didacticiels de Démarrage pour toutes les plateformes et les langages de programmation concernés.
  • Un lien vers tous les didacticiels vidéo d’un service donné.
  • Des liens vers du contenu de référence sur les API.
  • Un lien pour télécharger toute la documentation d’un service.
capture d’écran 18

Nouvelle table des matières

Nous avons profité de la migration vers docs.microsoft.com/azure pour améliorer la cohérence dans la navigation de la table des matières. Même si chaque service a ses propres caractéristiques, vous pouvez désormais voir une navigation similaire quand vous naviguez sur le site.

Colorisation améliorée

Pour les exemples de code qui représentent l’Interface de ligne de commande (CLI) Azure, nous avons ajouté une colorisation des paramètres et des mots clés afin de faciliter la lecture et la compréhension de notre code.

capture d’écran 19

Amélioration des références

L’un des principaux points sensibles dont vous nous avez fait part est que notre contenu sur les API, la ligne de commande et PowerShell n’est jamais à jour. Dès qu’Azure change, notre flux de travail manuel hérité ne fonctionne plus.

Pour cette version, nous avons modifié nos systèmes pour créer des références directement à partir du code source. Le nouveau contenu est publié en même temps que les nouvelles builds. Vous pourrez contribuer à la partie générée automatiquement de la documentation comme vous le faisiez avec notre contenu Procédures.

Nous normalisons également l’utilisation de la spécification Open API (anciennement Swagger) pour décrire nos API REST, ce qui nous donne désormais une représentation cohérente des données pour les services REST pouvant être utilisée pour la documentation et pour les SDK des clients. À l’avenir, nous serons aussi en mesure d’ajouter des fonctionnalités interactives à notre documentation REST et aux exemples de contenu de demande/réponse.

Pour cette version, nous avons activé :

capture d’écran 20capture d’écran 21

Documentation Visual Studio 2017 RC

Toute la documentation de Visual Studio est maintenant intégrée directement à l’expérience docs.microsoft.com nouvelle et mise à jour.

Nouvelle page hub pour Visual Studio

La page hub de Visual Studio comprend des liens clés qui vous permettront de démarrer avec la version Release Candidate de Visual Studio 2017.

Ils incluent le Guide d’installation, les Nouveautés et des didacticiels de Démarrage. Du contenu traduit sera bientôt disponible. Du nouveau contenu sera disponible sur des sujets tels que la refactorisation, l’utilisation de code qui n’est pas dans un projet, le débogage des problèmes de performances, des conseils sur l’optimisation du temps de démarrage de Visual Studio, des détails sur toutes les nouvelles fonctionnalités de productivité et de navigation du code dans l’éditeur, et bien plus encore.

Maintenant que Visual Studio prend en charge un processus d’installation entièrement personnalisable où vous obtenez uniquement les composants que vous souhaitez utiliser, vous pouvez approfondir sur son fonctionnement pour vos projets de développement, que vos charges de travail concernent la plateforme ASP.NET, Azure, Python ou Windows.

Documentation ASP.NET et Entity Framework Core

Nous avons aussi procédé à la migration de la documentation ASP.NET Core et Entity Framework Core, respectivement à partir de docs.asp.net et GitHub.

Référence ASP.NET / Entity Framework

ASP.NET Core et Entity Framework Core étant des projets open source, nous avons intégré étroitement leur code source et commentaires à trois barres obliques pour générer la documentation de référence d’API respective. Cela signifie que l’API et la documentation resteront toujours synchronisées automatiquement.

Documentation C++

En réponse aux demandes de longue date de nos clients, nous avons refactorisé la référence C++ dans un format plus compact qui nécessite moins de liens entre les rubriques. Vous trouverez désormais tous les documents pour les membres de classe dans la même rubrique que la classe.

Vous pourrez aussi en savoir plus sur les dernières modifications de mise en conformité aux normes C++ et sur les nouvelles options de build, telles que /fastlink, utiliser les nouveaux conseils relatifs au portage pour mettre à niveau votre code à partir des versions précédentes de Visual Studio, et découvrir comment tester la nouvelle prise en charge de la génération sur les systèmes Linux avec gcc.

Documentation SQL sur Linux

SQL Server sur Linux (qui fait partie de SQL Server vNext Customer Technical Preview 1) est disponible. Vous pouvez l’essayer dès maintenant. La page hub comprend des liens qui vont du démarrage à la gestion et au développement avec SQL Server sur Linux. Du contenu traduit sera bientôt disponible.

Conclusions

Notre objectif est de vous fournir encore plus de fonctionnalités sur le nouveau site de documentation et de faire en sorte que l’expérience soit cohérente avec nos produits et services. Étant donné que vous, l’utilisateur, êtes l’élément le plus critique dans le processus de documentation, nous vous encourageons à nous contacter et à nous faire part de vos commentaires sur la façon dont nous pouvons améliorer cette expérience pour vous sur Twitter.