An Update on the MSDN and TechNet Migration to docs.microsoft.com

This post was written by Jeff Sandquist, Corporate Vice President, Developer Relations.

Today, we are excited to give you an important update on the migration of MSDN and TechNet content to docs.microsoft.com. This blog post documents the last few steps of a company-wide effort to overhaul the content structure, format and the underlying infrastructure, and centralize Microsoft technical documentation around one site.

From MSDN and TechNet to docs.microsoft.com

Back in 1992, Microsoft Developer Network was born as a customer subscription service to provide technical information on programming for Windows. Six years later, in 1998, the MSDN Online site was launched, hosting more than 250,000 pages of content.

Screenshot of MSDN Online in 1999

Back then, the publishing process consisted of creating content in Microsoft Word, converting it into HTML, and publishing through a tool called pubwiz (Publishing Wizard). For over 20 years the process supported the release of new products, services and updates, resulting in a staggering 45 million pages of technical content!

As the product release cycle shifted from years to months, the demand for accessible up-to-date documentation grew. The publishing system needed to match the engineering velocity, and so we decided to re-invent how we manage documentation at Microsoft in the cloud era. In November 2015, the founding members of the docs.microsoft.com team - Dan Fernandez, Mary McHale, Carol Zeumault, and Jeff Sandquist wrote a document named “A New Hope” (a homage to Star Wars Episode IV), that outlined the vision for the new site. It included a set of key guiding principles:

  • Unified technical documentation. The new site should consolidate the dozens of documentation websites hosted by Microsoft. A developer learning how to create a data-driven web app would only need to visit one site to find all relevant content on ASP.NET, Azure, Entity Framework or any other Microsoft technology.
  • Improved user experience. A key factor in defining the success of a website is the experience it provides to its customers. The new site should have a better loading performance, readable fonts, accessible tables of contents, human-readable URLs, support for versioning, compatibility with mobile browsers, and follow the practices of inclusive design through accessible features and support for internationalization.
  • Democratize authoring and community engagement. The new site should be powered by open-source standards and tools, that empower anyone to create and edit documentation. It should be using Markdown for content, YAML for automatically-generated API documentation and rely on GitHub as the underlying content layer, which would allow the use of automated quality checks. The MicrosoftDocs GitHub organization has grown to over 7,400 members, and the Azure documentation repository is one of the fastest growing open source projects (470% year over year) and the 5th most contributed to repo in all of GitHub, as seen in The State of the Octoverse 2018!
  • Support API documentation. The new site should have first-class support for documentation of APIs written for programming languages and platforms our customers use including .NET, Java, Python, JavaScript and TypeScript, PowerShell, Azure CLI, Q#, OpenAPI and more. The experience should be powered by automation, have reliable API coverage and be able to publish API documentation in minutes rather than weeks.
  • Modernize the engineering infrastructure. docs.microsoft.com should run on Azure, allowing us to reduce maintenance costs (over $7MM saved), improve deployment times from every three weeks to daily (or faster) and reduce engineering duplication.
  • Extensible by default. As the site evolves, it must be able to meet the needs of our customers in the most efficient way. By making this commitment, we were able to build and integrate a brand new interactive learning experience - Microsoft Learn, as well as our sample code browser.

With a modern platform in place, we set out to ensure that we're not losing valuable content by migrating it to the new site. Below you will find more information on our progress.

MSDN and TechNet Libraries

Status: ✅ Complete

We started the migration of MSDN Library and TechNet Library to docs.microsoft.com in late 2017, and completed the migration this year.

The libraries previously provided documentation for Microsoft products, including API documentation, sample code, and technical articles. Originally available via CDs, the content later moved online with the launch of the MSDN and TechNet websites.

The migration required the conversion of a variety of XML-based formats to Markdown for human-edited content and YAML for auto-generated API documentation, spanning over one hundred various content sets. We have ensured that page redirects are in place for millions of web pages, preventing broken links referenced outside our site, such as blogs and forums.

To give you a glimpse into the volume of content we worked with, here are a few stats:

If you have bookmarked any MSDN or TechNet content, the links will be redirected seamlessly to their new location on docs.microsoft.com.

MSDN Magazine

Status: ✅ Complete

The last issue of MSDN Magazine was published on November 1, 2019. We sent a final message to readers and authors in the August edition of MSDN Magazine.

MSDN Magazine content that was published on MSDN has been moved to docs.microsoft.com/archive.

MSDN Magazine subscribers who paid for their subscriptions will receive a pro-rated refund, based on time remaining on their subscription. The refund checks will be mailed out after the November issue has published. This change does not impact the MSDN Platform Subscription.

Microsoft Developer and TechNet Flash Newsletters

Status: ✅ Complete

Newsletters that were published on MSDN and TechNet have been moved to docs.microsoft.com/archive.

Current subscribers will continue to receive these newsletters. We may evolve and change the format as well as the publication schedule.

If you no longer wish to subscribe to our newsletters, you can unsubscribe from the next email you receive.

MSDN and TechNet blogs

Status: 🚧 In progress

We have made the MSDN Blogs and TechNet Blogs sites read-only in July 2019. We are in the process of archiving all MSDN and TechNet blogs to docs.microsoft.com/archive. The migration is expected to complete in January 2020.

If you've bookmarked any MSDN or TechNet blogs, the links to those will seamlessly redirect to the new location on docs.microsoft.com/archive.

Status: ✅ Complete

We have redirected all MSDN Code Gallery pages to the samples browser and archived key samples to GitHub in the MicrosoftArchive organization. Read more about this process in our recent blog post.

You can find the most up-to-date code samples on docs.microsoft.com/samples.

Status: 🚧 In progress

The TechNet Gallery will be retiring in early 2020. In December 2019, the site will be made read-only no longer accept new community contributions. Additional announcements and information to follow.

Use docs.microsoft.com/samples to find the most up-to-date code samples. If you have previously contributed to the TechNet Gallery, make sure you migrate your samples to a personally-managed location, such as your own GitHub repository.

TechNet Wiki

Status: 🚧 In progress

We are working on a more concrete migration plan and schedule for TechNet Wiki. Please check back later for additional details. You can continue to participate and interact with wiki content at this time.

MSDN and TechNet Forums

Status: 🚧 In progress

We announced the preview release of Microsoft Q&A, which replaces MSDN and TechNet forums. To ensure a smooth transition and minimize disruption, we’ve broken down the migration into multiple phases. We expect to complete the migration by mid-2020. Please check back later for additional details.

Channel 9

Status: 🚧 In progress

Channel 9 continues to be an important investment for developer-focused video content. We are working on a migration path that will better integrate our videos and technical content from Channel 9. Please check back later for additional details.

We want to hear from you

We are excited to continue investing in our platform and make sure that you get the most relevant and reliable technical documentation for the entire Microsoft ecosystem. Give us your thoughts and improvement suggestions on GitHub and Twitter.