Microsoft revises document site

printing pressSoftware King of the World, Microsoft, has finally revamped its site for those who actually read the instructions for its software.

Microsoft’s developer documentation was once cutting edge and copied by everyone.  It used something radical called JavaScript and XML techniques which made it easy to browse through the documentation and quickly switch between related portions.

But over the years “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.  The changes broke URLs, so that both internal and external links to the documentation broke or bounced you through numerous redirects.

Vole has announced a new plan to overhaul both its TechNet and MSDN documentation to make it work. Documentation will have a new site, docs.microsoft.com, with a new consistent look and features.

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 mark-up language. All pages will also have both commenting and annotating using LiveFyre, putting an end to the current commenting system.

The URLs are being revised, hopefully for the last time, and the new URLs will be readable and, 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.