Docs update: add NuGet package instructions (#2720)

.cspell/dot-net.txt

@@ -1,7 +1,9 @@
 aspnet
 ASPNETCORE
 ASSERTE
+autoinstrumentation
 Bootstrapper
+buildtasks
 callq
 CLSID
 CONTRACTL

docs/README.md

@@ -18,8 +18,9 @@ can be found [here](https://github.com/open-telemetry/opentelemetry-dotnet-instr
 ## Quick start
 
 If you'd like to try the instrumentation on an existing application before
-learning more about the configuration options and the project, follow
-these instructions:
+learning more about the configuration options and the project, follow the
+instructions at [Using the OpenTelemetry.AutoInstrumentation NuGet packages](./using-the-nuget-packages.md#using-the-opentelemetryautoinstrumentation-nuget-packages)
+or use the appropriate install script:
 
 - On Linux and macOS, use the [shell scripts](#shell-scripts).
 - On Windows, use the [PowerShell module](#powershell-module-windows).
@@ -100,7 +101,7 @@ See [config.md#instrumented-libraries-and-frameworks](config.md#instrumented-lib
 ### Considerations on scope
 
 Instrumenting [`self-contained`](https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained)
-applications is going to be supported through [NuGet packages](./internal/using-the-nuget-packages.md).
+applications is supported through [NuGet packages](./using-the-nuget-packages.md).
 Note that a `self-contained` application is
 automatically generated in .NET 7.0 whenever the `dotnet publish` or `dotnet build`
 command is used with a Runtime Identifier (RID) parameter, for example when `-r`

docs/developing.md

@@ -99,6 +99,28 @@ mkdir $destFolder
 $artifacts | % { $dest = $(Join-Path $destFolder $_); $zip = $(Join-Path $zipFilesFolder $_) + ".zip"; Expand-Archive $zip $dest }
 ```
 
+Now you are ready to build the packages locally:
+
+```cmd
+dotnet nuke BuildNuGetPackages
+```
+
+to run the tests locally use:
+
+```cmd
+dotnet nuke TestNuGetPackages
+```
+
+To use the locally built NuGet packages in other projects on the local machine ensure
+that the target project is either using a `nuget.config`, adding `<repo>/bin/nuget-artifacts/`
+to the NuGet sources for example the
+[`nuget.config` used by the NuGet packages test applications](../test/test-applications/nuget-packages/nuget.config),
+or the packages are added to the project by specifying the `--source` parameter
+when running [`dotnet add package` command](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-add-package).
+
+Notice that package references are also cached so if you rebuild be sure to clean-up
+the cached versions too.
+
 ### Documentation lint
 
 If you made changes to the Markdown documents (`*.md` files), ensure that lint

docs/troubleshooting.md

@@ -129,6 +129,13 @@ To handle dependency versions conflicts,
 update the instrumented application's project references
 to use the same versions as OpenTelemetry .NET Automatic Instrumentation.
 
+A simple way to ensure that no such conflicts happen is to add the
+`OpenTelemetry.AutoInstrumentation` package to your application.
+For instructions about how to add it to your application, see
+[Using the OpenTelemetry.AutoInstrumentation NuGet packages](./using-the-nuget-packages.md#using-the-opentelemetryautoinstrumentation-nuget-packages)
+.
+
+Alternatively add only the conflicting packages to your project.
 The following dependencies are used by OpenTelemetry .NET Automatic Instrumentation:
 
 - [OpenTelemetry.AutoInstrumentation](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/src/OpenTelemetry.AutoInstrumentation/OpenTelemetry.AutoInstrumentation.csproj)

docs/using-the-nuget-packages.md

@@ -1,14 +1,5 @@
 # Using the OpenTelemetry.AutoInstrumentation NuGet packages
 
-> **Warning**
-> Currently, NuGet packages are only available as CI artifacts.
-When following these instructions, ensure that the packages are downloaded
-and that the target project is either using a `nuget.config` file configured to use
-the downloaded packages, for example the
-[`nuget.config` used by the NuGet packages test applications](../../test/test-applications/nuget-packages/nuget.config),
-or the packages are added to the project by specifying the `--source` parameter
-when running [`dotnet add package` command](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-add-package).
-
 ## When to use the NuGet packages
 
 Use the NuGet packages in the following scenarios:
@@ -18,6 +9,8 @@ Use the NuGet packages in the following scenarios:
   applications.
 1. Facilitate developer experimentation with automatic instrumentation through
   NuGet packages.
+1. Solve version conflicts between the dependencies used by the application and the
+  automatic instrumentation.
 
 ## Limitations
 
@@ -38,7 +31,7 @@ To automatically instrument your application with OpenTelemetry .NET add
 the `OpenTelemetry.AutoInstrumentation` package to your project:
 
 ```terminal
-dotnet add [<PROJECT>] package OpenTelemetry.AutoInstrumentation --source <PATH_TO_AUTO_INSTRUMENTATION_PACKAGES> --prerelease
+dotnet add [<PROJECT>] package OpenTelemetry.AutoInstrumentation --prerelease
 ```
 
 If the application references packages that can be instrumented, but, require
@@ -47,7 +40,7 @@ you to either add the missing instrumentation package or to skip the
 instrumentation of the corresponding package:
 
 ```terminal
-~packages/opentelemetry.autoinstrumentation.buildtasks/1.0.0-local.1/build/OpenTelemetry.AutoInstrumentation.BuildTasks.targets(29,5): error : OpenTelemetry.AutoInstrumentation: add a reference to the instrumentation package 'MongoDB.Driver.Core.Extensions.DiagnosticSources' version 1.3.0 or add 'MongoDB.Driver.Core' to the property 'SkippedInstrumentations' to suppress this error.
+~packages/opentelemetry.autoinstrumentation.buildtasks/1.0.0-rc.1/build/OpenTelemetry.AutoInstrumentation.BuildTasks.targets(29,5): error : OpenTelemetry.AutoInstrumentation: add a reference to the instrumentation package 'MongoDB.Driver.Core.Extensions.DiagnosticSources' version 1.3.0 or add 'MongoDB.Driver.Core' to the property 'SkippedInstrumentations' to suppress this error.
 ```
 
 To resolve the error either add the recommended instrumentation package or skip