Add markdown Readme for System.Text.Json

[MSDN-WhiteKnight]

I've decided to submit a PR for one of the popular packages to see how it would go.

Related to #59630

[ghost]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

I've decided to submit a PR for one of the popular packages to see how it would go.

Related to #59630

Author:	MSDN-WhiteKnight
Assignees:	-
Labels:	area-System.Text.Json
Milestone:	-

[eiriktsarpalis]

Is dotnet/runtime is the appropriate repo to maintain product documentation? We tend to use dotnet/docs and dotnet/dotnet-api-docs for that purpose. I think it might be preferable if the NuGet simply linked to the System.Text.Json documentation instead.

If we do add a README.md to the System.Text.Json, I think it might be preferable if it contained resources specific to developing/contributing to the library, e.g. STJ-specific instructions on coding conventions, testing, etc. that might somehow deviate from the repo-wide dev workflow guide.

cc @ViktorHofer @jkotas

[MSDN-WhiteKnight]

I think it's useful to have embedded markdown readme, mainly to help users who come from search engines into Nuget package page understand what's this package for and how to use it. Note that there's already mini-documentation in plaintext embedded into .csproj (PackageDescription); this change enables to use Markdown so it could contain links and formatting. I can remove example if it's too hard to maintain it. I was thinking it's good to add quick usage example on package page, that helps to start using library.

If we do add a README.md to the System.Text.Json, I think it might be preferable if it contained resources specific to developing/contributing to the library

The main point of this is to display the readme on Nuget gallery page, it should be user-oriented doc. Including contributor-oriented docs would be against the intended purpose. Well, such docs could also be added into the repo, but they don't need to be embedded into package.

[eiriktsarpalis]

I can remove example if it's too hard to maintain it.

If it's meant to function as a token code sample, then it probably won't require maintenance. But if it's just a token code sample, arguably a link to the up-to-date documentation is more valuable.

[eiriktsarpalis]

Looks good in principle, although I'd just remove the Example & Commonly Used Types sections. With the library constantly evolving (e.g. inclusion of sourcegen last year) I think it will be difficult to keep up-to-date. The link to the docs should provide relevant context.

[ViktorHofer]

cc @danmoseley @carlossanlop regarding embedding documenting directly into our packages.

[eiriktsarpalis]

Thanks!

[ViktorHofer]

Thank you

[eiriktsarpalis]

Many thanks @MSDN-WhiteKnight 👍