Microsoft unveils new effort to make its developer, IT documentation great again

Docs written in Markdown, with fixes submitted through GitHub.

Microsoft's developer documentation used to be the model that all others should follow. The documentation itself was thorough, combining reference material with usage guides and sample code. Its use of, at the time, novel JavaScript and XML techniques (known in those days as dynamic HTML, or DHTML) made it easy to browse through the documentation and quickly switch between related portions. But successive "updates" to MSDN Library have made it harder and harder to use, obscuring the consistent structure and organization and becoming much less useful to developers as a result. These updates had other side effects, often breaking URLs, so that both internal and external links to the documentation broke or bounced you through numerous redirects.

After years of ad hoc changes to its documentation system, Microsoft has announced a new plan to overhaul both its TechNet and MSDN documentation to make it fit for the purpose. Documentation will have a new site, docs.microsoft.com, with a new consistent look and features.

Some teams within Microsoft, such as those developing ASP.NET and .NET Core, had already open sourced their documentation. On the new site, all documentation will be handled similarly. Every article will have an "edit" button enabling changes and fixes to be proposed. These changes will be handled as pull requests on GitHub, with the documentation itself using the popular [Markdown markup language]. All pages will also have both commenting and annotating using LiveFyre, putting an end to the ugly commenting system currently used.

Another welcome change is that the URLs are being revised, hopefully for the last time ever. The new URLs will be human readable and, hence, related to their content. This should make the traditional MSDN link-breaking a thing of the past.

Microsoft also claims that the new documentation is much faster to load. Long articles will also be broken into shorter sections, something likely to help with load times.

To get things started, the Enterprise Mobility documentation has been published on the new site to give a taste for how it will look and feel.

What we don't have yet is any developer documentation, and my suspicion is that this still isn't going to bring back the greatly missed table-of-contents and split view that once upon a time made the MSDN documentation so good. The new design certainly looks better, and the new system for commenting and editing should ensure that the documentation itself will be more accurate and up-to-date than it currently is—but the core usability of the documentation doesn't look like it's gaining the improvements that it needs. Ever since Microsoft dropped its DHTML site, exploring and understanding its enormous range of APIs has been harder than it should be, and it doesn't look like the new site is going to fix that.