Improve package readme

[thompson-tomo]

Summary

I wish for the base nuget package to have a more informative readme.

Details

The base nuget package should be using the same readme as the repo to make it as easy as possible for a user to get started with the package.

[jskeet]

I disagree with the premise here. I think a website readme and a package readme have different purposes. I can agree with the summary in this issue, but not the details.

I view a package readme as something which should:

• Give enough information for the user to decide whether or not this is a useful package for them
• Tell them where to find more information

A lot of the README doc at the moment really isn't aimed at the average NuGet consumer - it's about governance of CloudEvents etc.

I think we should have a dedicated NuGet-specific README instead, with:

• A succinct summary of the package
• A single example (and we'll need to think about how to choose that)
• A link to the user guide
• A link to the repo root

I think that would be more useful to a NuGet consumer than the current full README.

In an ideal world, we'd have a different example and summary for each package.

[captainsafia]

@jskeet I agree with your assessment here. If it's any help, here are references to some of the PACKAGE.md files that are used for various packages that we ship out of .NET.

• https://github.com/dotnet/aspnetcore/blob/main/src/OpenApi/src/PACKAGE.md
• https://github.com/dotnet/aspnetcore/blob/08b60af1bca8cffff8ba0a72164fb7505ffe114d/src/Security/Authentication/JwtBearer/src/PACKAGE.md
• https://github.com/dotnet/runtime/blob/f9c08462ba81a2aacc9fd85d321e12080c17b9ee/src/libraries/System.Text.Json/src/PACKAGE.md

We don't have to follow it directly but I find the pattern of documenting key features, some usage info, and a list of key types to be helpful for users wanting to decide if the package is the right thing for them to use.

If the format looks good to you, I'd be happy to take a stab at opening a PR.

[jskeet]

@captainsafia wrote:

If the format looks good to you, I'd be happy to take a stab at opening a PR.

That would be wonderful - thanks so much! It would clearly be simpler to have a single package readme shared by all packages, although slightly more useful to have one per package. I'll leave it up to you to consider the path to take :)

[erwinkramer]

Not sure why #309 was closed, maybe introduce a very minimal PackageReadmeFile for each relevant project (just a few lines and basic structure), and go from there?

[captainsafia]

@erwinkramer I closed the PR because my bandwith/role changed and I didn't have the cycles to shepherd it through. However, I think the contents are a good starting point for future PRs.

[jskeet]

@erwinkramer If you have the time for the "minimal package readme file per project" that would be fabulous. Alternatively, if we had a single package-oriented readme for all packages as an interim measure, it would still be better than nothing.

[erwinkramer]

@jskeet, yes... like clockwork: #336

[jskeet]

Fab. I'll probably do a release in a couple of weeks, when we think we've done everything to catch up, so to speak.