La documentation de Microsoft dédiée aux développeurs pourrait être le modèle que tous les autres devraient suivre. La documentation elle-même était complète, combinant des références sur le matériel, avec des guides d’utilisation et des exemples de code. Son usage, à l’époque, alliant le JavaScript et le XML (techniques connues à l’époque où l’on parlait de HTML dynamique, ou DHTML), faisait qu’il était facile de naviguer à travers la documentation, et de basculer rapidement entre les parties reliées.
Mais, les « mises à jour » successives apportées à MSDN Library n’ont pas facilité son utilisation, obscurcissant la structure et l’organisation, et devenant en conséquence beaucoup moins utiles pour les développeurs. Ces mises à jour ont eu d’autres effets secondaires, provoquant quelques liens brisés, de sorte que les deux internes et externes menaient à des pages inaccessibles, ou à de nombreuses redirections.
Après des années de changements internes sur son système de documentation, Microsoft a annoncé un nouveau plan de refonte à la fois pour TechNet, et sa documentation MSDN pour l’adapter à cette fin. La documentation va être visible sur un nouveau site, accessible depuis le site docs.microsoft.com, et offrant un nouveau look cohérent, riche en fonctionnalités.
Microsoft Enterprise Mobility pour commencer !
Certaines équipes au sein de Microsoft, comme celles développant en ASP.NET et .NET Core, avaient déjà ouvert le code source de leur documentation. Sur le nouveau site, toute la documentation est traitée de façon similaire. Chaque article a un bouton « Edit » permettant des modifications et des corrections à proposer. Ces changements seront traités comme des pull requests sur GitHub. Il convient de noter que la documentation utilise le même langage de balisage Markdown.
Un autre changement bienvenu est que les URL sont en cours de révision, et espérons-le, pour la dernière fois. Les nouvelles URL seront lisibles par l’homme et, par conséquent, liées à son contenu. Microsoft affirme également que la nouvelle documentation est beaucoup plus rapide à charger. Les articles longs seront également divisés en sections plus courtes, ce qui devrait améliorer les temps de chargement.
Pour commencer, la documentation Microsoft Enterprise Mobility a été publiée sur le nouveau site pour nous donner un avant-goût de la façon dont elle va s’articuler. Ce que nous ne disposons pas encore est de toute la documentation pour les développeurs, et je soupçonne que cela risque de prendre un peu de temps avant que tout le contenu soit transféré.
Alors, qu’en pensez-vous ?
