The path towards better documentation

August 22, 2016 by Karan Nandwani

Update 9/20 (11:00 A.M PST): The revamped NuGet Docs experience is now live on docs.nuget.org. Read more about it here - New experience for NuGet Documentation

docs.nuget.org is the authoritative guide on everything NuGet. It is used as reference by nearly 180k developers with over 500k page views a month. Summary of the most consistent feedback we heard is given below:

  1. The grouping is not intuitive and makes it difficult to find the right document.
  2. Figuring out the end to end steps to build packages for new platforms is hard.
  3. Lack of indexing and cross referencing makes it difficult navigate between samples, reference docs and release notes.
  4. Some items only appear in release notes and blogs, but do not appear in the final docs.

In this post, we are going to talk about the changes we recently made based on your feedback, and plans going forward.

Before diving into details, we would like to thank a number of people who have helped us review and give feedback on these changes or inspired us to write new guides. Some of them have written a number of blog posts and tools that has significantly helped the community in understanding various package authoring techniques, NuGet concepts and APIs. There are many more who provided feedback through issues, tweets and other channels.

What did we change?

We have revamped the NuGet docs experience and we have a preview for you to try out. NuGet Docs Preview addresses the majority of feedback from the community. Just to be clear, we are not replacing docs.nuget.org just yet.

We have made several improvements including:

  1. New quick-starts for creating and consuming packages.
  2. End to end guides for new platforms such as .NET Standard and UWP.
  3. A simpler and more intuitive organization of topics.
  4. Left pane of contents serves as an index and allows you to glance at all topics.
  5. Cross-references with links to recommended reading, related topics and reference docs.
  6. And finally, a modern look and feel to the docs site.

new nuget docs landing page

How are the new docs organized?

  1. Quickstarts - These are very basic guides for both authors and consumers to get started
  2. Guides - The idea here is to give you everything you need to know to execute a scenario end to end. Some of the key guides we have built are:
  3. Creating, Consuming and Hosting packages
  4. Tools, Schema, API and Visual Studio Extensibility - Reference documentation
  5. Policies - FAQs, Governance, and the policy around Dispute resolution and Deleting packages
  6. Contribute guidance has been moved to the Nuget/Home wiki on Github

Will my existing references break?

No, existing references will not break. When we update docs.nuget.org, we’ll have permanent redirects in place that will redirect you to the new page.

How can I Contribute?

We made the contribution link a lot more obvious. Every page that allows contribution has a “Edit in Github” link right at the top. This link will you take you to the md file. Feel free to make changes and create a PR from your branch. The NuGet team will review the change and work with you to get it in.

edit in github

If you would like to raise a request for new docs or changes to existing docs, feel free to open a new issue.

What are we going to do moving forward?

With the advent of .NET Core, the NuGet community is growing by leaps and bounds. We understand that we have to lower the barrier to entry to make it easy for authors to create packages and for users to consume them. The first step there is to have fantastic documentation in place that enables this.

Over the next two weeks, we’ll closely look at any feedback on NuGet Docs Preview and iron out any wrinkles before updating the old site (docs.nuget.org).

In the coming quarter, we are looking into starting our docs migration into docs.microsoft.com similar to .NET Core documentation. Since NuGet and .NET are tied at the hip for the majority of its use cases, it’ll make it easier for our users to find and reference docs. In addition, we’ll have a consistent way to get feedback and enable contributions to docs from our users.

We want to hear your feedback!

We want NuGet to meet the evolving needs of our community. If you would like share your pain points and your current and future needs, use the calendly link to set up a quick 15-30 min call with us. If you would like to send us an email instead, hit us up at feedback@nuget.org.

You can also leave a comment below, and as always, if you run into any issues or have an idea, open an issue on GitHub.