Above: the new docs.microsoft.com appearance. Below: the same article in old TechNet. (credit: Microsoft)

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.