Add package readmes

[ViktorHofer]

Contributes to #59630

One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.

Ask

To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.

Why

The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.

How

This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.

I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.

Priority 1 (.NET 8 RC 2)

Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.

The below list is sorted by download count.

Package		Status
Microsoft.Extensions.DependencyInjection	Edit	✅
Microsoft.Extensions.Logging	Edit	✅
Microsoft.Extensions.DependencyInjection.Abstractions	Edit	✅
Microsoft.Extensions.Hosting	Edit	✅
Microsoft.Extensions.Hosting.WindowsServices	Edit	✅
Microsoft.Extensions.Logging.Abstractions	Edit	✅
Microsoft.Extensions.Http	Edit	✅
System.IO.Ports	Edit	✅
System.Data.OleDb	Edit	✅
Microsoft.Extensions.Options	Edit	✅
System.Management	Edit	✅
Microsoft.Extensions.Options.ConfigurationExtensions	Edit	✅
Microsoft.Extensions.Caching.Memory	Edit	✅
Microsoft.Extensions.Logging.Console	Edit	✅
Microsoft.Extensions.Hosting.Abstractions	Edit	✅
System.Text.Encoding.CodePages	Edit	✅
Microsoft.Bcl.AsyncInterfaces	Edit	✅
System.DirectoryServices.AccountManagement	Edit	✅
System.Speech	Edit	✅
System.DirectoryServices	Edit	✅
Microsoft.Extensions.Logging.Debug	Edit	✅
System.Net.Http.Json	Edit	✅
System.Data.Odbc	Edit	✅
Microsoft.Extensions.Primitives	Edit	✅
Microsoft.Bcl.Numerics (new package)	Edit	✅
Microsoft.Bcl.TimeProvider (new package)	Edit	✅

Priority 2 (.NET 8 / .NET 9)

This list is sorted alphabetically.

Package		Status
Microsoft.Bcl.Cryptography	Edit
Microsoft.Extensions.Caching.Abstractions	Edit
Microsoft.Extensions.Configuration	Edit	✅
Microsoft.Extensions.Configuration.Abstractions	Edit	✅
Microsoft.Extensions.Configuration.Binder	Edit	✅
Microsoft.Extensions.Configuration.CommandLine	Edit
Microsoft.Extensions.Configuration.EnvironmentVariables	Edit
Microsoft.Extensions.Configuration.FileExtensions	Edit
Microsoft.Extensions.Configuration.Ini	Edit
Microsoft.Extensions.Configuration.Json	Edit
Microsoft.Extensions.Configuration.UserSecrets	Edit
Microsoft.Extensions.Configuration.Xml	Edit
Microsoft.Extensions.DependencyInjection.Specification.Tests	Edit
Microsoft.Extensions.DependencyModel	Edit
Microsoft.Extensions.FileProviders.Abstractions	Edit
Microsoft.Extensions.FileProviders.Composite	Edit
Microsoft.Extensions.FileProviders.Physical	Edit
Microsoft.Extensions.FileSystemGlobbing	Edit
Microsoft.Extensions.Hosting.Systemd	Edit
Microsoft.Extensions.Logging.Configuration	Edit
Microsoft.Extensions.Logging.EventLog	Edit	✅
Microsoft.Extensions.Logging.EventSource	Edit
Microsoft.Extensions.Logging.TraceSource	Edit
Microsoft.Extensions.Options.DataAnnotations	Edit
Microsoft.NET.WebAssembly.Threading	Edit
Microsoft.Win32.Registry.AccessControl	Edit
Microsoft.Win32.SystemEvents	Edit
Microsoft.XmlSerializer.Generator	Edit
System.CodeDom	Edit
System.Collections.Immutable	Edit
System.ComponentModel.Composition	Edit
System.ComponentModel.Composition.Registration	Edit
System.Composition	Edit
System.Composition.AttributedModel	Edit
System.Composition.Convention	Edit
System.Composition.Hosting	Edit
System.Composition.Runtime	Edit
System.Composition.TypedParts	Edit
System.Configuration.ConfigurationManager	Edit
System.Diagnostics.DiagnosticSource	Edit
System.Diagnostics.EventLog	Edit	✅
System.Diagnostics.PerformanceCounter	Edit
System.DirectoryServices.Protocols	Edit
System.Formats.Cbor	Edit
System.IO.Hashing	Edit
System.IO.Packaging	Edit
System.IO.Pipelines	Edit
System.Memory.Data	Edit
System.Net.Http.WinHttpHandler	Edit	✅
System.Numerics.Tensors	Edit
System.Reflection.Context	Edit
System.Reflection.Metadata	Edit
System.Reflection.MetadataLoadContext	Edit
System.Resources.Extensions	Edit
System.Runtime.Caching	Edit
System.Runtime.Serialization.Schema	Edit
System.Security.Cryptography.Cose	Edit
System.Security.Cryptography.Pkcs	Edit
System.Security.Cryptography.ProtectedData	Edit
System.Security.Cryptography.Xml	Edit
System.Security.Permissions	Edit
System.ServiceModel.Syndication	Edit
System.ServiceProcess.ServiceController	Edit
System.Text.Encodings.Web	Edit
System.Text.Json	Edit	✅
System.Threading	Edit
System.Threading.AccessControl	Edit
System.Threading.Channels	Edit	✅
System.Threading.RateLimiting	Edit
System.Threading.Tasks.Dataflow	Edit
System.Windows.Extensions	Edit

✅ (:white_check_mark:) -> reviewed & approved

🕜 (:clock130:) -> under review

cc @lyndaidaii @ericstj @danmoseley @jeffhandley @MSDN-WhiteKnight

[ghost]

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

Issue Details

---

Contributes to #59630

One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.

Ask

To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.

Why

The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.

How

This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.

For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md

I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.

Priority 1 (.NET 8 RC 2)

Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.

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

Prio 2 (.NET 8 / .NET 9)

• Microsoft.Bcl.Cryptography
• Microsoft.Bcl.Numerics
• Microsoft.Bcl.TimeProvider
• Microsoft.Extensions.Caching.Abstractions
• Microsoft.Extensions.Caching.Memory
• Microsoft.Extensions.Configuration
• Microsoft.Extensions.Configuration.Abstractions
• Microsoft.Extensions.Configuration.Binder
• Microsoft.Extensions.Configuration.CommandLine
• Microsoft.Extensions.Configuration.EnvironmentVariables
• Microsoft.Extensions.Configuration.FileExtensions
• Microsoft.Extensions.Configuration.Ini
• Microsoft.Extensions.Configuration.Json
• Microsoft.Extensions.Configuration.UserSecrets
• Microsoft.Extensions.Configuration.Xml
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.DependencyInjection.Abstractions
• Microsoft.Extensions.DependencyInjection.Specification.Tests
• Microsoft.Extensions.DependencyModel
• Microsoft.Extensions.FileProviders.Abstractions
• Microsoft.Extensions.FileProviders.Composite
• Microsoft.Extensions.FileProviders.Physical
• Microsoft.Extensions.FileSystemGlobbing
• Microsoft.Extensions.Hosting
• Microsoft.Extensions.Hosting.Abstractions
• Microsoft.Extensions.Hosting.Systemd
• Microsoft.Extensions.Hosting.WindowsServices
• Microsoft.Extensions.Http
• Microsoft.Extensions.Logging
• Microsoft.Extensions.Logging.Abstractions
• Microsoft.Extensions.Logging.Configuration
• Microsoft.Extensions.Logging.Console
• Microsoft.Extensions.Logging.Debug
• Microsoft.Extensions.Logging.EventLog
• Microsoft.Extensions.Logging.EventSource
• Microsoft.Extensions.Logging.TraceSource
• Microsoft.Extensions.Options
• Microsoft.Extensions.Options.ConfigurationExtensions
• Microsoft.Extensions.Options.DataAnnotations
• Microsoft.Extensions.Primitives
• Microsoft.NET.WebAssembly.Threading
• Microsoft.Win32.Registry.AccessControl
• Microsoft.Win32.SystemEvents
• Microsoft.XmlSerializer.Generator
• System.Collections.Immutable
• System.ComponentModel.Composition
• System.ComponentModel.Composition.Registration
• System.Composition
• System.Composition.AttributedModel
• System.Composition.Convention
• System.Composition.Hosting
• System.Composition.Runtime
• System.Composition.TypedParts
• System.Configuration.ConfigurationManager
• System.Diagnostics.DiagnosticSource
• System.Diagnostics.PerformanceCounter
• System.DirectoryServices.Protocols
• System.Drawing.Common
• System.Formats.Cbor
• System.IO.Hashing
• System.IO.Packaging
• System.IO.Pipelines
• System.Memory.Data
• System.Net.Http.WinHttpHandler
• System.Numerics.Tensors
• System.Reflection.Context
• System.Reflection.Metadata
• System.Reflection.MetadataLoadContext
• System.Resources.Extensions
• System.Runtime.Serialization.Schema
• System.Security.Cryptography.Cose
• System.Security.Cryptography.Pkcs
• System.Security.Cryptography.ProtectedData
• System.Security.Cryptography.Xml
• System.ServiceModel.Syndication
• System.Text.Encoding.CodePages
• System.Text.Json
• System.Threading
• System.Threading.AccessControl
• System.Threading.Channels
• System.Threading.RateLimiting
• System.Threading.Tasks.Dataflow

cc @lyndaidaii @ericstj @danmoseley @jeffhandley

Author:	ViktorHofer
Assignees:	-
Labels:	area-Meta
Milestone:	8.0.0

[carlossanlop]

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:

<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.

[lyndaidaii]

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:

<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.

There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.

[ericstj]

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.

addressed