Introducing .NET Core Docs
This post was written by Jeff Sandquist, General Manager in the Cloud + Enterprise Division.
Today we released a preview of the .NET Documentation on docs.microsoft.com. To learn more about the new documentation experience improvements docs.microsoft.com offers, visit the introducing docs.microsoft.com blog post. In addition to having all the collaborative features, open-sourced content, and friendlier URLs available on the docs.microsoft.com platform, we've introduced some new features specific to .NET developers. This post will highlight these new features and summarize our plans for the future.
Highlights of the .NET Documentation Experience
To accompany the exciting RTM release of .NET Core we're putting it front and center in the .NET Documentation home page. To complement the .NET Core RTM release with everything you'll need to get started quickly, we've put links to articles and a new reference experience at the top of the list.
The .NET Ecosystem at Your Fingertips
You'll see links to download the new .NET Core libraries, ASP.NET, Entity Framework, Azure, using Xamarin to build iOS applications using .NET, and building Universal Windows Platform (UWP) apps using .NET. We haven't moved all of the .NET content over to docs.microsoft.com quite yet, but the .NET Documentation home page will be your starting point to get to all .NET documentation.
Articles
Our writers and engineers, as well as a few dedicated community members, have been working tirelessly creating new .NET Core-related articles you'll find in the .NET Documentation section. Here you'll find a range of articles like:
These and many other topics are all presented in the docs.microsoft.com theme, with a clean table of contents on each page, as well as the estimated time to read each article and contributor information for each article.
All .NET articles are open-source and available on GitHub in the .NET team's docs repository. If you find any issues in the documentation or want to improve it, doing so is as easy as clicking the edit button in the right navigation of each article.
Editing an article is as simple as clicking the edit button on any of the Markdown files in the repository, adding your content, and submitting a pull request. Once one our team reviews and accepts your pull request, your contributions will go live on the site in minutes.
API Reference
In addition to the great content being authored by our writers, engineers, and passionate community members, we've made significant improvements to the reference experience. The reference experience has been completely redesigned in this preview release, borrowing on the same design principles we used in the docs.microsoft.com articles.
Like those articles, the new references pages are responsive, designed with modern web principles, and will look better on mobile devices.
We've added a Type Search to all Namespace pages. This enables you to easily search by type name for all .NET types. With each keypress, we filter the list of types being shown in the left navigation. This exciting new feature of the reference area is included in our new framework for generating .NET reference documentation known as DocFX, an open-source project on GitHub).
As you click on individual types in the left navigation for any namespace, you'll hop directly to the namespace page's introduction section to that type. By clicking the name of the type in the main area of the reference content you'll see the class's detail page, which contains the class's inheritance chain, declaration, and details about the class's property and method members.
For each method member you'll see details on the parameters and a summary of the method.
Information and Engineering Principles
In addition to continued development and improvement on the DocFX document-generation tools, we've made significant improvements to the engineering and documentation principles you'll see evident in the new .NET Documentation experience.
Better Automation
When pull requests are received from potential contributors, we validate that the contributor has followed a simple process of signing our Contributor License Agreement (this process is fully electronic and takes a matter of minutes to complete). As long as the contributions adhere to the Contribution Guidelines, small changes should appear live on the site minutes after pull requests are accepted.
Better URLs
One important principle of the overall docs.microsoft.com experience is better URLs to improve search indexing and "guessing." We've maintained this principle in the .NET Documentation. Both the articles and reference documentation have cleaner URLs. Take for example the classic MSDN URL for the System namespace:
In the new reference documentation, the URL is more logical, human-readable, and most importantly, more discoverable.
More Agile and Open Authoring
The content is not only open-source, and we not only accept community contributions. In addition, all of the content on docs.microsoft.com (including the .NET Documentation) is all available under a Creative Commons license. You can read it, copy it, reference it, and re-use parts of it (even for commercial use). The writers and engineers have been working with community members actively for months in the new system. It has been an interesting and exciting transition, and we have more to come in the future.
Future Plans
This section of docs.microsoft.com, as is the rest of the site, is still in preview, so we're encouraging constructive feedback and commentary. Please submit your feature ideas to UserVoice.
In the coming weeks, we will be publishing the XML comments that are used to generate reference documentation directly into the .NET source code. This will enable anyone to easily click update the .NET Framework reference documentation.
We will also continue to tweak the design and layout of the reference, as well as the aforementioned ability to edit the reference content itself.
We're excited to bring you the new .NET Documentation area on docs.microsoft.com, and we look forward to making your experience better in the future!