Docs : Microsoft renouvelle complètement sa documentation technique

Docs : Microsoft renouvelle complètement sa documentation technique

Il y a comme... un léger mieux

Avatar de l'auteur
Vincent Hermann

Publié dans

Internet

04/05/2016 4 minutes
24

Docs : Microsoft renouvelle complètement sa documentation technique

Microsoft travaille actuellement sur une révision en profondeur de son site dédié à ses diverses documentations pour les développeurs et professionnels. L’éditeur n’hésite pas à décrire l’actuel comme « archaïque ».

Microsoft dispose depuis bien longtemps d’une vaste documentation pour ceux qui ont besoin de manipuler ses technologies. La bibliothèque la plus connue est sans conteste MSDN (Microsoft Developer Network) qui regroupe des renseignements et exemples sur l’ensemble des produits, langages, API et autres proposés aux développeurs. L’autre, que connaissent bien les professionnels, est TechNet.

Des sites poussiéreux

Considérant le nombre très élevé de solutions disponibles chez le géant, il n’est pas surprenant que cette volumineuse documentation soit devenue vaste au point de créer des problèmes d’accessibilité, qu’il s’agisse de MSDN ou de TechNet. Et pour cause : « Les deux sites ont été bâtis sur une base de code fragile datant d’il y a 10-15 ans avec un système archaïque de publication et de déploiement qui n’a jamais été prévu pour fonctionner dans le cloud ».

Microsoft indique donc avoir demandé l’avis de centaines de développeurs et professionnels, tout en suivant les suggestions sur le site UserVoice. Globalement, il était demandé à la firme d’aller au-delà des « murs de textes » en fournissant à ceux qui en avaient besoin des solutions et des mesures proactives, afin que l’ensemble soit beaucoup moins statique.

Lisibilité et responsive design

Le site docs.microsoft.com fait son apparition, en préversion pour le moment. Premier changement, la lisibilité des articles, dont les lignes sont beaucoup plus courtes (une taille maximale a été fixée) et la police plus grande. Deux demandes apparemment régulières des utilisateurs. Chaque article dispose en outre d’une date de publication et d’un temps estimé de lecture.

La réorganisation du contenu est également un élément clé. Chaque grande section correspondant à un produit ou une technologie est accompagnée désormais de plusieurs points mis en avant et classés par thématiques : découvrir, planification, déploiement, gestion, problèmes, services, etc. Une classification qui se retrouve propulsée aussi dans la barre latérale gauche, qui reprend l’index de la documentation globale sur le sujet.

Outre un ensemble passé à la moulinette du responsive design (adaptation automatique à la taille de l’écran, surtout sur les appareils mobiles), Microsoft profite de l’occasion pour revoir la documentation elle-même. L’éditeur s’est en particulier attaqué aux très longs articles techniques, qui pouvaient se montrer décourageant par leur volume. De nombreux textes ont donc été divisés en sections logiques, accompagnés d’éléments de navigation pour se déplacer dans les chapitres. Microsoft ajoutera par la suite une fonction permettant de réunir l’ensemble des chapitres au sein d’un document PDF récupérable.

microsoft docs documentation technet msdn

Une documentation open source

La nouvelle documentation se veut également beaucoup plus axée sur la communauté. Elle passe donc en open source, comme celles d’ASP.NET, Azure, .NET Core et Graph. Chaque article est accompagné d’un bouton de modification qui permet d’accéder aux sources du fichier Markdown correspondant sur GitHub. Toute modification crée une pull request qui sera inspectée par la suite.

Les pages d’articles seront également munies d’un bouton permettant de les commenter. Pour cette fonction, Microsoft s’est associée à… Livefyre, tout juste racheté par Adobe. Il faudra se connecter pour laisser un commentaire, mais la société laisse le choix des armes : Twitter, Facebook, Google, Yahoo, ou le compte Microsoft évidemment. Le partage est lui aussi simplifié, soit pour un article entier (via un bouton dédié), soit à partir d’une simple sélection de texte. Enfin, Docs peut être utilisé sous deux thèmes, clair et sombre.

24

Écrit par Vincent Hermann

Tiens, en parlant de ça :

Sommaire de l'article

Introduction

Des sites poussiéreux

Lisibilité et responsive design

Une documentation open source

Commentaires (24)


« Les deux sites ont été bâtis sur une base de code fragile datant

d’il y a 10-15 ans avec un système archaïque de publication et de

déploiement qui n’a jamais été prévu pour fonctionner dans le cloud ».

c’est de frontpage <img data-src=" />



très loin (m’enfou dredi ici)


C’est pas trop tôt. En plus, le site est une horreur sans nom a charger sur ie.


il y avait plus simple comme procédure

&nbsp;

cd /var/www/www.MSDN.com&nbsp;

wget –recursive&nbsp;–convert-links&nbsp;http://stackoverflow.com/questions/tagged/msdn



done.&nbsp;


Y’a pas wget sous Windows&nbsp;<img data-src=" /> (ok, on peut l’ajouter)








v1nce a écrit :



il y avait plus simple comme procédure

&nbsp;

cd /var/www/www.MSDN.com&nbsp;

wget –recursive&nbsp;–convert-links&nbsphttp://stackoverflow.com/questions/tagged/msdn



done.&nbsp;





Ah, ça, le nombre de fois où j’ai une question un peu spé et où j’ai plus vite fait de taper mes mots clés dans Google et cliquer sur le premier lien stackoverflow plutôt que de chercher dans la MSDN…



Carrement, lire les articles Technet est si rebarbatif…en plus les articles sont inegaux, certains sont excellents et bien ecris (How DNS Works/DHCP/Windows Time), et d’autres…no comment…oui Sharepoint c’est de toi que je parle :)))


Super nouvelle! C’était imbuvable!


Si l’idée c’était de passer d’une documentation technique pointue à un billet de blog simpliste, c’est une réussite totale.


<img data-src=" />



L’idée même de doter les pages de documentation d’un bouton pour commenter laisse présager du pire, effectivement… <img data-src=" /> <img data-src=" />


Je viens d’aller faire un tour et c’est… pas terrible pour l’instant lol On verra bien comment ça évoluera! En espérant que ça fasse pas comme la transition Sdz =&gt; OpenClassRoom….




Toute modification crée une pull request qui sera inspectée par la suite.



Clair qu’ils ont intérêt d’inspecter, parce que sinon ça allait troller grave avec les anti-krosof de tout poil <img data-src=" />


“qui n’a jamais été prévu pour fonctionner dans le cloud”

Je comprends pas le sens de cette phrase. Le site n’était pas héberger sur un serveur? Qu’es-ce qui vienne nous raconter avec leur cloud ?? C’est pour placer le mot à la mode??



Opensource vu par MS: possibilité de copier sur github utilisé ici comme un clone de wiki par contre sur le satut juridique des articles (sous CC ou similaire), tintin!!


Le plus gros problème introduits récemment dans une portion de MSDN c’est l’interface Metro-like du site. Deux des portions importantes du site à savoir le fil d’ariane d’un article et le bloc de gauche qui liste d’autres articles ou des méthodes, etc. sont tronqués et y figurent beaucoup de “…”. C’est donc devenu vraiment chiant de s’y repérer, déjà que c’était pas forcément génial avant non plus.


il y a un thème dark&nbsp;<img data-src=" />



après le reste c’est msdn en mieux organisé donc ce n’est pas mal mais pas révolutionnaire&nbsp;<img data-src=" />








v1nce a écrit :



il y avait plus simple comme procédure

&nbsp;

cd /var/www/www.MSDN.com&nbsp;

wget –recursive&nbsp;–convert-links&nbsphttp://stackoverflow.com/questions/tagged/msdn



done.&nbsp;





voyou !

&nbsp;

&nbsp;<img data-src=" />



“Une taille maximale a été fixée”… C’est quoi cette idée de m ? Ils vont nous faire le truc en mode feedbuzz aussi ? Cliquez sur suivant pour voir les paramètres, Likez-nous sur fb pour voir les examples ?



Ils feraient mieux de mettre des trucs utils genre pour la MSDN intégrer le site où il y a les sources du framework, ou un testeur en ligne (un truc à la swagger)



Cette nouvelle doc suit une tendance que j’ai vue côté applis W8/10/UAP ; c’est soit disant rangé, par thème etc. et perso je retrouve souvent pas ce que je veux aussi facilement car faut deviner dans quelle catégorie ca serait.


Pas convaincu du tout par la démo. Le gros avantage de MSDN, pour moi qui suis dév, c’est de trouver les détails sur un objet / une méthode, et bien souvent des exemples clairs. Sur la présentation des concepts c’est bien souvent à revoir, mais ce n’est pas le site qui est en cause, mais bien souvent les articles eux-mêmes. Changer de plateforme n’aura pas un gros INpact là-dessus.


Perso je trouve que MSDN fait parfaitement le taf en ce qui concerne la description des objets/membres.&nbsp;

Et stackoverflow fait parfaitement le taf pour tout le reste.

Je suis pas sûr que faire un genre de mix entre les 2 soit la bonne idée ou alors il faut avoir la qualité de réponse qu’on trouve sur stackoverflow ce qui est loin d’etre les cas des 3 ou 4 questions résolues sur les forums microsoft…








hollaamic a écrit :



“Une taille maximale a été fixée”… C’est quoi cette idée de m ? Ils vont nous faire le truc en mode feedbuzz aussi ? Cliquez sur suivant pour voir les paramètres, Likez-nous sur fb pour voir les examples ?



Ils feraient mieux de mettre des trucs utils genre pour la MSDN intégrer le site où il y a les sources du framework, ou un testeur en ligne (un truc à la swagger)



Cette nouvelle doc suit une tendance que j’ai vue côté applis W8/10/UAP ; c’est soit disant rangé, par thème etc. et perso je retrouve souvent pas ce que je veux aussi facilement car faut deviner dans quelle catégorie ca serait.









C’est la taille des lignes qui a une limite. Pas la taille de l’intégralité de l’article.



Sinon je trouve que c’est plutôt une bonne idée, y’en a partout actuellement, TechNet et MSDN en premier, mais pas que. (Genre ASP.Net 5 / Core 1.0 qui a son propre site :https://docs.asp.net)



Du moment que l’on perd pas en qualité d’information.









hollaamic a écrit :



“Une taille maximale a été fixée”… C’est quoi cette idée de m ? Ils vont nous faire le truc en mode feedbuzz aussi ? Cliquez sur suivant pour voir les paramètres, Likez-nous sur fb pour voir les examples ?











Jean Sébastien Gwak a écrit :



C’est la taille des lignes qui a une limite. Pas la taille de l’intégralité de l’article.







Pour être exact, c’est la largeur maximale de la colonne centrale.



“To improve content readability, we changed the site to have a set content width.”



(source: https://docs.microsoft.com/teamblog/introducing-docs-microsoft-com )









127.0.0.1 a écrit :



Pour être exact, c’est la largeur maximale de la colonne centrale.



“To improve content readability, we changed the site to have a set content width.”



(source: https://docs.microsoft.com/teamblog/introducing-docs-microsoft-com )







Effectivement, j’ai fais un raccourci un peu rapide, mais c’était ce que je voulais dire :)









domFreedom a écrit :



<img data-src=" />



L’idée même de doter les pages de documentation d’un bouton pour commenter laisse présager du pire, effectivement… <img data-src=" /> <img data-src=" />





Ouh pinaise, ceux qui vont se tromper en tapant MSDN au lieu de MSN vont se rendre sur la doc du SDK Windows 10 et faire des commentaires du style “en comprent rien a l’article mais s’est un coup des bobo islamo-sionistes communistes illuminati reptiliens à la solde de l’UMPS pour aidez les etrangé a avoir le RSA et volez not pain. Vivemant Marine”



Ça va être sympa…



Sans compter les trolls anti-Microsoft. J’espère qu’il y aura des filtres.





J’ai jeté un coup d’oeil sur le site, mais quand on voit que le premier produit mis en avant est InTune, cette daube DRMisé…


D’accord je trouvais ça un peu étonnant quand même, j’ai relu plusieurs fois pourtant (mais pas la source). Dans ce cas ça se tient déjà <img data-src=" />