Announcing a unified .NET reference experience on docs.microsoft.com
This post was written by Jeff Sandquist, General Manager in the Azure Growth and Ecosystem team.
Almost a year ago, we piloted the .NET Core reference documentation on docs.microsoft.com. Today we are happy to announce our unified .NET API reference experience. We understand that developer productivity is key - from a hobbyist developer, to a startup, to an enterprise. With that in mind, we partnered closely with the Xamarin team to standardize how we document, discover, and navigate .NET APIs at Microsoft.
All .NET documentation - in one place
Previously, if you wanted to find a .NET-based SDK shipped by Microsoft, you had to spend some time with your favorite search engine, trying to find both the place where you can download it, as well as discover the relevant API documentation.
Going forward, we plan to have all .NET-compatible SDKs unified and searchable in one place: https://docs.microsoft.com/dotnet/api. There, you'll find reference documentation for .NET Framework, .NET Core, .NET Standard and Xamarin, as well as documentation for our Azure NuGet packages. In the months to come, we'll add more SDKs to this experience.
Introducing the API Browser
Our main goal is to bring an IntelliSense-like experience to search all .NET APIs from a web browser. You can search for a namespace, class, method, or interface by typing its full or partial name directly in the API Browser page.
If you're not sure which SDK a specific type, member or namespace belongs to, you can simply select All APIs in the API scope dropdown and search across all available reference docs. Alternatively, if you want to limit your search, you can select a specific framework or SDK as well as its version - say, .NET Framework 4.7, and search only within that set of APIs.
The API Browser experience is also integrated at the top of the table of contents for .NET-based APIs, allowing you to quickly find any API no matter where you are within the reference documentation:
Once you are in a specific namespace, the API Browser is scoped only to the family of APIs that are connected together, so your search is always returning the best possible results based on your context.
You no longer have to wonder whether a type has members available in a specific version of .NET Framework or the Azure Storage NuGet package - all you need to do is change the version from the API Browser control, and the content will adjust accordingly:
Built with Open Source in mind
To build the API Browser, we used open standards and tools. At its core, we leveraged DocFX - the open documentation generation toolchain, along with Xamarin's mdoc application.
All our managed reference documentation is now auto-generated from binaries that ship on NuGet or are part of the main framework distributions, such as .NET Framework or .NET Core.
Our continuous integration infrastructure enables us to have accurate documentation for the latest APIs that can now be public within hours from release, open for contributions. We have also standardized all .NET API documentation on the ECMAXML format, which creates a consistent and comprehensive API representation regardless of the SDK being documented. Moreover, you don't need to know the intricacies of the file format, as you can contribute content in Markdown, embedded in auto-generated docs. Community contributions for reference documentation will be enabled within the next month.
Focus on content
In addition to the new experiences, we have also optimized the reference content to be more discoverable and readable. We've updated the table of contents to always be namespace-focused. Whether you're browsing information on a namespace, type or member, we will always show you just the parent namespace with all its children types & their respective grouped members:
Which means that reference pages are decluttered and show you the most important information first, such as general overviews and examples - all at a glance.
You will also see examples that are relevant to you right from the start, filtered to your programming language of choice - you no longer have to scroll to the very bottom of the page to find those.
This is just the start of us revamping the reference documentation experience. We want to hear your feedback on how we can make our documentation more engaging, useful and get you on your way as fast as possible. Go to our UserVoice site and let us know how we can improve our API Browser experience. You can also always reach out to us on Twitter, @docsmsft, for quick updates.