Introductory Source Link Documentation Leaves Much to be Desired #1378

This feedback relates to:

https://github.com/dotnet/sourcelink/blob/main/README.md

I've been applying it to a C# project using Net9.

1. The documentation buries the lead. It should start by giving a brief example of how to get this feature to work in "typical" environments, and then go on to explain the details, gotchas, etc.

2. The documentation is, so far as I can tell, flat out wrong, at least when it comes to trying to include Source Link info in a Net9/VS2022 (latest patches) project environment.

The instructions says for modern versions of VS you only need to include this in the PropertyGroup:

  <EmbedUntrackedSources>true</EmbedUntrackedSources>

However, if you do that, you Source Link will be invalid in the generated nuget package.

Instead, you must include this entry in PropertyGroup as well:

  <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>

then and only then will Source Link be valid.

Please correct the documentation.