Microsoft has announced a preview release of docs.microsoft.com, a new documentation service to replace MSDN and TechNet.

In the blog post announcing the docs.microsoft.com Jeff Sandquist explains that the new service had been designed in response to feedback on Microsoft's UserVoice forum. He writes:

It was clear we needed to make a change and create a modern web experience for content. The first thing we did was evaluate our existing content infrastructure TechNet and MSDN. Both sites are built on a 10-15 year-old brittle codebase with an archaic publishing and deployment system that was never designed to run on the cloud. 

He also states:

For years customers have told us to go beyond walls of text with feature-level content and help them implement solutions to their business problems. We knew that the content we delivered and the platform we built must make it easy for customers to learn and deploy solutions. 

The preview that has been made available is only for Enterprise Mobility Documentation, which consists of Advanced Threat Analytics, Azure Active Directory, Azure Remote App, Multi-factor Authentication, Azure Rights Management, Intune, and Microsoft Identity Manager. However the same model will be used for other content.

Among the key features on show are a set content width and increased font size for the navigation panel on the left. Article length is deliberately kept short and there is also an estimate of how long each article will take to read below the author's name.

Although the content for doc.microsoft starts out being authored by Microsofties the idea of open source documentation is that the community can have a say. You'll find tools to let you comment, edit and share content next to one that toggles between the Light and Dark theme.  

Microsoft has partnered with Livefyre to enable comment and Sidenotes to be made within every article. To do this you have to sign in using either your Microsoft account details or Twitter, Facebook, Google or Yahoo credentials. After this you can add comments or notes on each paragraph of content.

The Edit button takes you to the source Markdown file in GitHub where you can  submit a pull request to fix or improve content. The Share button lets you share content on Twitter or Facebook.

While no-one will disagree that there was room for improvement with Microsoft's documentation, is this the change we wanted? What is wanted is something that makes finding information quick and easy. On the other hand we don't want to lose access to obscure information that only a few people rely on. There is a great deal of history out there and it may be at risk of being discarded because its significance isn't recognized. There is also the fact that interests change and Microsoft's interests are no longer Visual Basic and the MFC but Universal Apps and all things Azure. Recreating the documentation from scratch will put a completely different emphasis on what the technology is. You also can't help the suspicion rising to the surface that this might also be another way for Microsoft to encourage us to move to the new. Is this documentation as marketing? 

While we are fully in favor of improved discoverability, don't let it be at the expense of throwing out information that Microsoft now views as obsolescent. There are plenty of perfectly workable systems that actively rely on older technologies.

Comments

Make a Comment or View Existing Comments Using Disqus

or email your comment to: comments@i-programmer.info