November update for docs.microsoft.com

This post was written by Jeff Sandquist, General Manager in the Cloud + Enterprise Division.

Today we are proud to announce that we have now migrated the documentation for Azure, Visual Studio 2017 RC, C++, ASP.NET Core, Entity Framework Core and SQL on Linux to docs.microsoft.com!

Bringing all of our content together will drive consistency of experience for our customers, for mobile support, localization, comments, social sharing, or community contributions.

While this is a big release, we will continue to update the content and site features regularly, so please make sure to send us UserVoice feedback on the content experience.

You can also look forward to the addition of content for Dynamics 365, Windows Server, SQL Server, System Center and Windows desktop over the coming months.

In This Post

  • Docs Key Features
  • New Docs Features
  • Azure Documentation
  • Visual Studio 2017 RC Documentation
  • C++ Documentation
  • ASP.NET Core Documentation
  • Entity Framework Core Documentation
  • SQL on Linux Documentation

Docs Key Features

For those of you not familiar with docs.microsoft.com, here are some of the key features of our new experience.

Estimated Reading Time and Last Updated

A simple enhancement we’ve made based on your input is provide an estimated reading time for an article. We know many of you are learning and evaluating technologies during those few minutes between meetings and you’re more likely to read articles if you knew how much of a time commitment is required.

We also added time stamps to content to help customers understand how fresh the content is - you no longer have to guess when was the last time an article was updated.

screenshot1

Responsive Design

To build a great experience on mobile devices, tablets, and PCs, we implemented a responsive layout. Clicking the Options button at the top of the page on small-screen devices will let you access the same options you would see on a desktop browser.

screenshot2

Global Documentation

We've heard time and time again from international customers on the importance of localized content. docs.microsoft.com now supports 45 languages, including right-to-left ones, such as Arabic and Hebrew, as well as 63 locales in total for Dynamics 365 content with fallback logic where localized docs may not be available. This makes our docs truly global and ready for the additional content coming in the new year.

screenshot3

screenshot4

Side-notes and Comments

Your questions, comments, and feedback are important to us. We’ve partnered with Livefyre to provide comments and side-notes on all of our articles. At the top of every article you’ll see an option to jump directly to the comments section.

We want to hear from you and we're committed to monitoring and responding to all comments and questions left on Docs pages.

screenshot5

To comment, you can log in using your existing Twitter, Facebook, Google, Yahoo, or Microsoft credentials.

screenshot6

In addition, you will be able to follow the threads where you expect follow-ups - always be in the know when one of our team or community members has responded to you.

screenshot7

You can also add side-notes on each content paragraph or specifically highlighted text. To do that, simply select a chunk of text with the mouse cursor or click on the comment icon that appears on the right side of the paragraph as you hover over it.

screenshot8

Social Sharing

The sharing button at the top of the page lets you easily share our content to your Twitter followers and Facebook friends.

screenshot9

You can also select content directly with your mouse to share it via the contextual widget.

screenshot10

Light / Dark Theme

We also added a theme picker so that you can change between a light and a dark theme, something that some of you have asked for on UserVoice.

screenshot12

User-friendly URLs

We care about our web experience and one thing that regularly bugged us as users of TechNet and MSDN is that articles didn't have friendly, readable URLs. Here’s an example of the same article with our new URLs.

Before

https://technet.microsoft.com/en-us/library/dn646983.aspx3

After

https://docs.microsoft.com/en-us/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune

Community Contributions

The vast majority of the docs on our site are enabled for community contributions. Simply click on the Edit button in the top right menu to go to the corresponding GitHub page, fork the repo, make a change, and submit your pull request. We welcome edits on localized content and feedback on the overall contribution experience as well!

screenshot13

New Docs features

While many of those features have been around since our launch day in May, we've also added a number of new features, outlined below.

Real-time Table of Contents Filter

We've enabled our Table of Contents to be instantly filterable. What that means is that you can easily type just a few characters to filter any matching text to find the content you're looking for.

screenshot14

Left-navigation Table of Contents

Another key feature we've added addresses the problem of content on multiple sites. Should an article on deploying an ASP.NET app to Azure App Service be listed under Azure or ASP.NET? The answer is both, but without duplicating the content on both site sections for discoverability and consistency reasons.

To do this, we enable content teams to select any content on docs and create a view of that content for customers. The picture below shows what a hypothetical layout could be for .NET Developers using Docker that may have content that ships from the Azure, ASP.NET, .NET Core, and the Visual Studio Azure SDK teams - all in a single view.

screenshot15

Verifiable Code Samples

One of the most frustrating features of documentation is when the presented or linked samples don't, in fact, work on your machine. At Microsoft, we have thousands of code samples and snippets and we want to make sure our customers can trust that those samples work on the supported platforms and configurations.

To do that, we've developed an extensible Continuous Integration (CI) system, to ensure the samples compile and produce the expected output for a given set of operating systems and toolchains. While we're working to onboard more teams on this, we want to ensure that users who download our code are confident in it passing all the necessary quality checks.

Integrated Reference Content

We've redesigned the underlying DocFX engine, the open-source component that powers docs.microsoft.com, to include language bindings for different platforms and formats. This includes support for:

  • Azure CLI (Python)
  • PowerShell
  • .NET and .NET Core
  • Java
  • Swagger / REST APIs

What this means for customers is that the documentation should no longer drift out-of-sync with API capabilities as there is now one source of truth that drives both the docs and the code. You can read more about the specific support for API reference in the Azure and ASP.NET/EF sections below.

PDF Support

Another major feature that customers have been asking for is PDF support - you can download a specific set of docs without it taking gigabytes of space, and take it with you anywhere, whether you are on a desktop or mobile device.

To enable that, we've turned on PDF support for our table of contents. We made sure that the PDF file is updated when the content is updated on the live site, so that you are always getting the latest and greatest of our content.

<img alt="screenshot16]()

Azure Documentation

We have heard your feedback about fragmentation and challenges with the experience, so we are well on our journey to migrate our Azure technical documentation from azure.microsoft.com, MSDN, and GitHub and consolidate it on https://docs.microsoft.com/azure/.

New Azure Hub Page

We also have taken the opportunity to change the look and feel of the landing page for Azure content. Some key highlights include:

screenshot17

New Service Page

We've ensured our landing pages are consistent and link to key resources including:

  • A Service Overview link.
  • Getting Started tutorials for all relevant platforms and programming languages.
  • A link to all video tutorials for a given service.
  • Links to API reference content.
  • A link to download all documentation for that service.

screenshot18

New Table of Contents

As we move to docs.microsoft.com/azure we are taking this opportunity to improve consistency on Table of Contents navigation. While each service has unique characteristics you will now see similar navigation as you move around the site.

Improved Colorization

For code samples that represent the Azure Command Line Interface (CLI), we added colorization for keywords and parameters so that you'll have an easier time reading and understanding our code.

screenshot19

Reference Improvements

One of the biggest pain points we've heard from all of you is that our API, command-line, and PowerShell content are never up-to-date. As quickly as Azure changes, our legacy manual workflows don't work.

For this release, we have changed our systems to create reference directly from source code. When new builds are delivered, new content will be delivered as well. And just like you could contribute to our How To content, you will be able to do the same to auto-generated part of the documentation.

We are also standardizing on the use of the Open API Specification (formerly known as Swagger) to describe our REST APIs, which will now give us a consistent data representation for REST services that can be used for documentation as well as client SDKs. In the future we'll also be able to add interactive features to our REST documentation and example request/response payloads.

For this release we have enabled:

screenshot20

screenshot21

Visual Studio 2017 RC Documentation

We are introducing all Visual Studio documentation, integrated directly in the new and updated docs.microsoft.com experience.

New Visual Studio Hub Page

The Visual Studio Hub page includes key links to get started with the Release Candidate of Visual Studio 2017.

This includes the Installation Guide, What's New, and Getting Started tutorials. Localized content will be coming soon. New content will be available for topics such as refactoring, working with code that isn't in a project, debugging performance issues, tips on optimizing Visual Studio startup time, details on all the new productivity and code navigation features in the editor, and more.

Now that Visual Studio supports a completely customizable installation process, where you get only the components you want to use, you can learn more about how this works for your individual development projects, regardless of whether your workloads involve ASP.NET, Azure, Python, or Windows platforms.

ASP.NET and Entity Framework Core Documentation

ASP.NET Core and Entity Framework Core documentation were also migrated from docs.asp.net and GitHub respectively.

ASP.NET / Entity Framework Reference

Since ASP.NET Core and Entity Framework Core are open source projects, we've deeply integrated their source code and triple-slash comments to build the respective API reference documentation. What that means is the API and documentation will always stay in sync, automatically.

C++ Documentation

In response to long-standing requests from customers, we've refactored the C++ reference into a more compact format that requires fewer links between topics. Now, you can find all the docs for class members in the same topic as the class.

In addition, learn more about the latest C++ standards conformance changes and new build options like /fastlink, use the new porting guidance to upgrade your code from the previous versions of Visual Studio, and discover how to try out the new support for building on Linux systems with gcc!

SQL on Linux Documentation

SQL Server on Linux (part of the SQL Server vNext Customer Technical Preview 1) is here and ready for you to try! The Hub page includes key links that take you from getting started to managing and developing with SQL Server on Linux. Localized content is coming soon.

Conclusions

We are eager to deliver even more features to the new documentation site and ensure that the experience is consistent with our products and services. Because you, the user, are the most critical piece in the documentation process, we encourage you to reach out to us and give feedback on how we can make this experience better for you - either through UserVoice or Twitter.