Embedded markdown readme for NuGet packages

[MSDN-WhiteKnight]

NuGet introduced embedded markdown Readme support in May 2021. Now the updated gallery design displays this readme file on the package page if it's included. Looks like most runtime packages don't have readme embedded (neither markdown nor plaintext), and for them it fallbacks to description from nuspec. This leads to experience like this:

A lot of space is unused here. It could be filled with some more introductory information or simple usage example. And also listed "Commonly used types" could be links to their API docs. That's how package with markdown readme looks like:

Could we add markdown readme files for runtime packages?

---

Progress:

• microsoft.extensions.configuration
• microsoft.extensions.configuration.json
• system.configuration.configurationmanager
• system.text.json
• microsoft.extensions.configuration.binder
• microsoft.extensions.configuration.abstractions
• System.Runtime.Caching

For up-to-date checklist, see PR #91210

See also:

• Write a high-quality README for NuGet packages
• Package Readme guidelines
• Example PR with new Readme template

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[ghost]

Tagging subscribers to this area: @Anipik, @safern, @ViktorHofer
See info in area-owners.md if you want to be subscribed.

Issue Details

---

NuGet introduced embedded markdown Readme support in May 2021. Now the updated gallery design displays this readme file on the package page if it's included. Looks like most runtime packages don't have readme embedded (neither markdown nor plaintext), and for them it fallbacks to description from nuspec. This leads to experience like this:

A lot of space is unused here. It could be filled with some more introductory information or simple usage example. And also listed "Commonly used types" could be links to their API docs. That's how package with markdown readme looks like:

Could we add markdown readme files for runtime packages?

Author:	MSDN-WhiteKnight
Assignees:	-
Labels:	enhancement, area-Infrastructure-libraries, packaging, untriaged
Milestone:	-

[joperezr]

That is a good suggestion. Moving issue to infrastructure as the change to add markdown for package descriptions would likely go there. We can consider using third-party libraries that convert a (markdown) string into html. We could use one of those and then let individual packages onboard markdown description as they see fit.

[ViktorHofer]

Would this actually require any infrastructure support? I assume a library author just needs to set a property to point to the manually written markdown file.

[joperezr]

I'm not sure how this works, I assumed that in order for this to work then you should need to write the description in Html so that the Nuspec is able to parse it and show it in nuget.org. In any case, even if that is not the case and all we need to do is to change the description to markdown, I believe infrastructure has usually been the owners of package ddescription so I'd imagine that we should do an overall pass through all packages to make the conversion.

[svick]

@joperezr The relevant documentation is here. In short, the readme file has to be in Markdown, so no extra work for converting it is needed.

[ViktorHofer]

I'm wondering if it makes more sense to convert every library's existing PackageDescription property content into README.md markdown files or just keep it as is and let library authors decide if they would like to leverage the README.md support.

Pros for converting now:

• Easier to add content to what's already there

Cons:

• Adding a README.md file per project and shipping it via our packages even though most packages won't have any additional information that would warrant a README.md file.

[MSDN-WhiteKnight]

Better to convert individual libraries as needed, i think. This is mainly needed for out-of-band libraries that are explicitly installed via package manager. For libraries like System.Collections.Immutable that are inbox on all .NET Core versions and only installed via package manager for .NET Framework, it's less important.

We also need to define convention where readme.md is placed in projects. Should it be docs\README.md as in NuGet default example, or just README.md near .csproj file?

[ViktorHofer]

We also need to define convention where readme.md is placed in projects. Should it be docs\README.md as in NuGet default example, or just README.md near .csproj file?

No need for another folder. I would just put it next to the csproj file.

[joperezr]

I think that when it comes to infrastructure, one more pro to call out from @ViktorHofer list is consistency. Having all OOB packages use the same process to add the package description makes it easier to maintain and understand for the rest of the folks working on the repo, so my vote is either on moving all to README.md files, or not onboarding into markup, but not be in an in-between state.

[loic-sharma]

Hey there! I'm from the NuGet team. Here are instructions on how to add a README to a package: https://docs.microsoft.com/en-us/nuget/reference/msbuild-targets#packagereadmefile

NuGet's internal telemetry (Microsoft only) indicates these packages would be good candidates:

• microsoft.extensions.configuration
• microsoft.extensions.configuration.json
• microsoft.extensions.dependencyinjection
• system.net.http
• system.configuration.configurationmanager
• microsoft.extensions.logging
• system.text.json
• microsoft.extensions.configuration.binder
• microsoft.extensions.configuration.abstractions
• microsoft.extensions.dependencyinjection.abstractions
• microsoft.extensions.logging.abstractions
• microsoft.extensions.http
• microsoft.extensions.hosting

For context, we'd like to drive README adoption in the .NET ecosystem (Microsoft only again, sorry! 😅). Please let us know if you have any questions or feedback on the README experience, we'd be happy to help!

/cc @chgill-MSFT

[eerhardt]

convert every library's existing PackageDescription property content into README.md markdown files

My thinking is that README files are better with content - especially code snippets. Looking at the example from above

I think the "How to Use" section provides a lot of value to people new to the package. I wouldn't want to author that markdown in an MSBuild property in the .csproj.

I think to make this a useful experience for our customers, we are going to want a separate .md file that the .csproj points to.

---

Also note that it looks like nuget.org already puts the PackageDescription into the README section if you don't have a README:

runtime/src/libraries/Microsoft.Extensions.DependencyInjection/src/Microsoft.Extensions.DependencyInjection.csproj

Line 10 in 4ae0dea

<PackageDescription>Default implementation of dependency injection for Microsoft.Extensions.DependencyInjection.</PackageDescription>

[ViktorHofer]

There's nothing that is stopping library owners in dotnet/runtime from adding a README.md file and packaging it, given that we migrated all libraries from the old pkgproj infrastructure to the NuGet Pack task during NET6.

I don't think it's a good strategy to convert every library's existing PackageDescription content to README.md files as in many cases that description is quite short and doesn't offer any details on how to actually use the exposed APIs. Instead, it sounds like package consumers would want us to include "Getting Started" documentation per package, which doesn't exist today.

Based on that, I'm moving this to area-Meta as there's nothing that the infrastructure team needs to provide.

[ghost]

Tagging subscribers to this area: @dotnet/area-meta
See info in area-owners.md if you want to be subscribed.

Issue Details

---

NuGet introduced embedded markdown Readme support in May 2021. Now the updated gallery design displays this readme file on the package page if it's included. Looks like most runtime packages don't have readme embedded (neither markdown nor plaintext), and for them it fallbacks to description from nuspec. This leads to experience like this:

A lot of space is unused here. It could be filled with some more introductory information or simple usage example. And also listed "Commonly used types" could be links to their API docs. That's how package with markdown readme looks like:

Could we add markdown readme files for runtime packages?

Author:	MSDN-WhiteKnight
Assignees:	-
Labels:	documentation, enhancement, area-Meta, packaging
Milestone:	7.0.0

[teo-tsirpanis]

@MSDN-WhiteKnight can you remove System.Net.Http from the task list? This package is legacy.

[ViktorHofer]

Do we actually want to package the README.md files from the source tree? Those include details about what kind of source changes we accept, sometimes describe the dotnet/runtime developer innerloop; and such target a different audience than the one that consumes the package.

cc @ericstj

[MSDN-WhiteKnight]

Probably not all of them. Ones that i were adding also contain information for package users, for example: https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.Extensions.Configuration.Binder/README.md

Microsoft.Extensions area owners preferred to consolidate library readme and package readme, so here it is one "merged" readme. But it is not the case for other libraries, for example, System.Text.Json now has two different readmes: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/README.md and https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/README.md

[ViktorHofer]

Microsoft.Extensions area owners preferred to consolidate library readme and package readme, so here it is one "merged" readme.

Interesting. Are we sure that we want to leak the internal repo specific documentation to consumers on nuget.org? That doesn't sound right to me.

[jeffhandley]

Do we actually want to package the README.md files from the source tree? Those include details about what kind of source changes we accept, sometimes describe the dotnet/runtime developer innerloop; and such target a different audience than the one that consumes the package.

Agreed; it was not intended for these recently-added READMEs to target library consumers. The audience for those is folks engaging within the repo source and the content is indeed different.

I could imagine having a PACKAGE.md at the root of the library folders where it's clear the purpose of that file is to be the markdown for the package.

[ericstj]

Agree with @jeffhandley, the package readme is different from our repo readme's. It's possible there is some overlap. Probably there are different conventions we could follow. I could imagine readme.md+package.md, readme.md+contributing.md, etc. Naming is not really blocking (though it should be consistent) - the premise of this issue is to leverage the readme feature of nuget to add more documentation to the packages.

I wonder if there is a way that this relates / intersects with our docs-source-of-truth efforts that are moving more of the API docs into the repo. Could we share some of that (eg: Namespace docs, for example) with the packages? cc @carlossanlop

[lyndaidaii]

Hi, I'm from the NuGet team. We are driving effort to increase the adoption and quality of NuGet package READMEs.

Here is .NET library package candidates that are top installed in Visual Studio.

• System.Data.OleDb
• System.Data.Odbc
• System.Management
• System.DirectoryServices.AccountManagement
• System.DirectoryServices
• System.ServiceProcess.ServiceController
• System.Windows.Extensions
• System.CodeDom
• System.Diagnostics.EventLog
• System.Runtime.Caching
• System.IO.Ports
• Microsoft.Bcl.AsyncInterfaces
• System.Speech
• System.Text.Encodings.Web
• System.Security.Permissions
• System.Net.Http.Json
• System.Drawing.Common

To help you get started, we suggest the following steps to include a README in your packages listed below:
• If you are new to NuGet README, learn more about how to add a README to your NuGet Package.
• Follow the README template and blog post for best practices.
• Check out a great example that created README for System.Text.Json that can be used for .NET libraries.
• Reach out to us for review or help.

[danmoseley]

@ViktorHofer what does this track that's not in #91210

[ViktorHofer]

This issue existed before we started working on package readmes in #91210. Let's close this issue in favor of the PR. After the PR is merged (this week), I'll open another issue for the remaining packages.