Best practice and local dev documentation updates (#1608)

* Refactored error model documentation into developer guidance section
* Minor changes to developer index page
* Fixed header on experimental attributes doc
* Grammar tweak
* Migrated into development section, fixed table to add missing version added numbers
* Added missing space
* Changed dev integrations title to more general dev guidance
* Rearranged guidance/development docs, added new landing page for "best practices" section
* Added best practices to main page

---------

Signed-off-by: Whit Waldo <[email protected]>

Author: WhitWaldo

daprdocs/content/en/dotnet-sdk-docs/_index.md

@@ -86,20 +86,27 @@ Put the Dapr .NET SDK to the test. Walk through the .NET quickstarts and tutoria
 
 ## More information
 
-Learn more about local development options, or browse NuGet packages to add to your existing .NET applications.
+Learn more about local development options, best practices, or browse NuGet packages to add to your existing .NET 
+applications.
 
 <div class="card-deck">
   <div class="card">
     <div class="card-body">
       <h5 class="card-title"><b>Development</b></h5>
-      <p class="card-text">Learn about local development options for .NET Dapr applications</p>
-      <a href="{{% ref dotnet-development %}}" class="stretched-link"></a>
+      <p class="card-text">Learn about local development integration options</p>
+      <a href="{{% ref dotnet-integrations %}}" class="stretched-link"></a>
+    </div>
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>Best Practices</b></h5>
+      <p class="card-text">Learn about best practices for developing .NET Dapr applications</p>
+      <a href="{{% ref dotnet-guidance %}}" class="stretched-link"></a>
     </div>
   </div>
   <div class="card">
     <div class="card-body">
       <h5 class="card-title"><b>NuGet packages</b></h5>
-      <p class="card-text">Dapr packages for adding the .NET SDKs to your .NET applications.</p>
+      <p class="card-text">NuGet packages for adding the Dapr to your .NET applications.</p>
       <a href="https://www.nuget.org/profiles/dapr.io" class="stretched-link"></a>
     </div>
   </div>

daprdocs/content/en/dotnet-sdk-docs/dotnet-development/_index.md

@@ -0,0 +1,53 @@
+---
+type: docs
+title: "Best Practices for the Dapr .NET SDK"
+linkTitle: "Best Practices"
+weight: 85000
+description: Using Dapr .NET SDK effectively
+---
+
+## Building with confidence
+
+The Dapr .NET SDK offers a rich set of capabilities for building distributed applications. This section provides 
+practical guidance for using the SDK effectively in production scenarios—focusing on reliability, maintainability, and 
+developer experience.
+
+Topics covered include:
+
+- Error handling strategies across Dapr building blocks
+- Managing experimental features and suppressing related warnings
+- Leveraging source analyzers and generators to reduce boilerplate and catch issues early
+- General .NET development practices in Dapr-based applications
+
+## Error model guidance
+
+Dapr operations can fail for many reasons—network issues, misconfigured components, or transient faults. The SDK
+provides structured error types to help you distinguish between retryable and fatal errors.
+
+Learn how to use `DaprException` and its derived types effectively [here]({{% ref dotnet-guidance-error-model.md %}}).
+
+## Experimental attributes
+
+Some SDK features are marked as experimental and may change in future releases. These are annotated with 
+`[Experimental]` and generate build-time warnings by default. You can:
+
+- Suppress warnings selectively using `#pragma warning disable`
+- Use `SuppressMessage` attributes for finer control
+- Track experimental usage across your codebase
+
+Learn more about our use of the `[Experimenta]` attribute [here]({{% ref dotnet-guidance-experimental-attributes.md %}}).
+
+## Source tooling
+
+The SDK includes Roslyn-based analyzers and source generators to help you write better code with less effort. These tools:
+
+- Warn about common misuses of the SDK
+- Generate boilerplate for actor registration and invocation
+- Support IDE integration for faster feedback
+
+Read more about how to install and use these analyzers [here]({{% ref dotnet-guidance-source-generators.md %}}).
+
+## Additional guidance
+
+This section is designed to support a wide range of development scenarios. As your applications grow in complexity, you'll find increasingly relevant practices and patterns for working with Dapr in .NET—from actor lifecycle management to configuration strategies and performance tuning.
+

daprdocs/content/en/dotnet-sdk-docs/dotnet-error-handling/_index.md

@@ -1,18 +1,18 @@
 ---
 type: docs
-title: "Richer Error Model in the Dapr .NET SDK"
-linkTitle: "Richer error model"
-weight: 59000
+title: "Error Model in the Dapr .NET SDK"
+linkTitle: "Error Model"
+weight: 85100
 description: Learn how to use the richer error model in the .NET SDK.
 ---
 
 The Dapr .NET SDK supports the richer error model, implemented by the Dapr runtime. This model provides a way for applications to enrich their errors with added context,
-allowing consumers of the application to better understand the issue and resolve faster. You can read more about the richer error model [here](https://google.aip.dev/193), and you
+allowing consumers of the application to better understand the issue and resolve it faster. You can read more about the richer error model [here](https://google.aip.dev/193), and you
 can find the Dapr proto file implementing these errors [here](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto").
 
 The Dapr .NET SDK implements all details supported by the Dapr runtime, implemented in the `Dapr.Common.Exceptions` namespace, and is accessible through
-the `DaprException` extension method `TryGetExtendedErrorInfo`. Currently this detail extraction is only supported for 
-`RpcException`'s where the details are present.
+the `DaprException` extension method `TryGetExtendedErrorInfo`. Currently, this detail extraction is only supported for 
+`RpcException`s where the details are present.
 
 ```csharp
 // Example usage of ExtendedErrorInfo
@@ -75,7 +75,7 @@ All details implement the abstract `DaprExtendedErrorDetail` and have an associa
 
 ## RetryInfo
 
-Information telling the client how long to wait before they should retry. Provides a `DaprRetryDelay` with the properties 
+Information notifying the client how long to wait before they should retry. Provides a `DaprRetryDelay` with the properties 
 `Second` (offset in seconds) and `Nano` (offset in nanoseconds).
 
 ## DebugInfo
@@ -91,11 +91,12 @@ a collection of `DaprQuotaFailureViolation`, which each contain a `Subject` (the
 ## PreconditionFailure
 
 Information informing the client that some required precondition was not met. Has one property `Violations`, a collection of 
-`DaprPreconditionFailureViolation`, which each has `Subject` (subject where the precondition failure occured e.g. "Azure"), `Type` (representation of the precondition type e.g. "TermsOfService"), and `Description` (further description e.g. "ToS must be accepted.").
+`DaprPreconditionFailureViolation`, which each has `Subject` (subject where the precondition failure occured, e.g. "Azure"), 
+`Type` (representation of the precondition type, e.g. "TermsOfService"), and `Description` (further description e.g. "ToS must be accepted.").
 
 ## RequestInfo
 
-Information returned by the server that can be used by the server to identify the clients request. Contains
+Information returned by the server that can be used by the server to identify the client's request. Contains
 `RequestId` and `ServingData` properties, `RequestId` being some string (such as a UID) the server can interpret,
 and `ServingData` being some arbitrary data that made up part of the request.
 
@@ -105,13 +106,13 @@ Contains a localized message, along with the locale of the message. Contains `Lo
 
 ## BadRequest
 
-Describes a bad request field. Contains collection of `DaprBadRequestDetailFieldViolation`, which each has `Field` (the offending field in request e.g. 'first_name') and
-`Description` (further information detailing the reason e.g. "first_name cannot contain special characters").
+Describes a bad request field. Contains collection of `DaprBadRequestDetailFieldViolation`, which each has `Field` (the offending field in request, e.g. 'first_name') and
+`Description` (further information detailing the reason, e.g. "first_name cannot contain special characters").
 
 ## ErrorInfo
 
-Details the cause of an error. Contains three properties, `Reason` (the reason for the error, which should take the form of UPPER_SNAKE_CASE e.g. DAPR_INVALID_KEY),
-`Domain` (domain the error belongs to e.g. 'dapr.io'), and `Metadata`, a key value based collection of futher information.
+Details the cause of an error. Contains three properties, `Reason` (the reason for the error, which should take the form of UPPER_SNAKE_CASE, e.g. DAPR_INVALID_KEY),
+`Domain` (domain the error belongs to, e.g. 'dapr.io'), and `Metadata`, a key/value-based collection with further information.
 
 ## Help
 
@@ -121,13 +122,13 @@ which provides `Url` (a url to help or documentation), and `Description` (a desc
 ## ResourceInfo
 
 Provides information relating to an accessed resource. Provides three properties `ResourceType` (type of the resource being access e.g. "Azure service bus"), 
-`ResourceName` (The name of the resource e.g. "my-configured-service-bus"), `Owner` (the owner of the resource e.g. "[email protected]"),
-and `Description` (further information on the resource relating to the error e.g. "missing permissions to use this resource").
+`ResourceName` (the name of the resource e.g. "my-configured-service-bus"), `Owner` (the owner of the resource e.g. "[email protected]"),
+and `Description` (further information on the resource relating to the error, e.g. "missing permissions to use this resource").
 
 ## Unknown
 
 Returned when the detail type url cannot be mapped to the correct `DaprExtendedErrorDetail` implementation.
-Provides one property `TypeUrl` (the type url that could not be parsed e.g. "type.googleapis.com/Google.rpc.UnrecognizedType").
+Provides one property `TypeUrl` (the type url that could not be parsed, e.g. "type.googleapis.com/Google.rpc.UnrecognizedType").
 
 
 

daprdocs/content/en/dotnet-sdk-docs/dotnet-guidance/_index.md

@@ -1,9 +1,9 @@
 ---
 type: docs
-title: "Dapr .NET SDK Development with Dapr CLI"
+title: "Experimental Attributes"
 linkTitle: "Experimental Attributes"
-weight: 61000
-description: Learn about local development with the Dapr CLI
+weight: 85200
+description: Learn about why we mark some methods with the `[Experimental]` attribute
 ---
 
 ## Experimental Attributes

daprdocs/content/en/dotnet-sdk-docs/dotnet-error-handling/dotnet-richer-error-model.md renamed to daprdocs/content/en/dotnet-sdk-docs/dotnet-guidance/dotnet-guidance-error-model.md

@@ -1,8 +1,8 @@
 ---
 type: docs
-title: "Overview of Dapr source code analysis"
-linkTitle: "Code Analysis"
-weight: 70000
+title: "Dapr source code analyzers and generators"
+linkTitle: "Roslyn Analyzers/Generators"
+weight: 85300
 description: Code analyzers and fixes for common Dapr issues
 no_list: true
 ---
@@ -13,7 +13,7 @@ from NuGet alongside each of the standard capability packages to enable these an
 
 {{% alert title="Note" color="primary" %}}
 
-A future release of the Dapr .NET SDK will include these analyzers by default without necessitating a separate package
+A future release of the Dapr .NET SDK will include these analyzers by default without requiring a separate package
 install.
 
 {{% /alert %}}
@@ -57,19 +57,19 @@ the `EnableNETAnalyzers` property to `false` in your csproj file.
 
 ## Available Analyzers
 
-| Diagnostic ID | Dapr Package | Category         | Severity     | Version Added                                                                                                                     | Description                                                                         | Code Fix Available |
-| -- | -- |------------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------| -- |
-| DAPR1301 | Dapr.Workflow | Usage | Warning      | 1.16                                                                                                                              | The workflow type is not registered with the dependency injection provider          | Yes |
-| DAPR1302 | Dapr.Workflow | Usage | Warning | 1.16                                                                                                                              | The workflow activity type is not registered with the dependency injection provider | Yes | 
-| DAPR1401 | Dapr.Actors | Usage            | Warning      | 1.16                                                                                                                              | Actor timer method invocations require the named callback method to exist on type   | No                 |
-| DAPR1402 | Dapr.Actors | Usage            | Warning      | The actor type is not registered with dependency injection                                                                        | Yes                                                                                 |
-| DAPR1403 | Dapr.Actors | Interoperability | Info         | Set options.UseJsonSerialization to true to support interoperability with non-.NET actors                                         | Yes                                                                                 |
-| DAPR1404 | Dapr.Actors | Usage            | Warning      | Call app.MapActorsHandlers to map endpoints for Dapr actors                                                                       | Yes                                                                                 |
-| DAPR1501 | Dapr.Jobs | Usage            | Warning      | Job invocations require the MapDaprScheduledJobHandler to be set and configured for each anticipated job on IEndpointRouteBuilder | No                                                                                  |
+| Diagnostic ID | Dapr Package | Category         | Severity     | Version Added                                                                                                                           | Description                                                                                                                        | Code Fix Available |
+| -- | -- |------------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| -- |
+| DAPR1301 | Dapr.Workflow | Usage | Warning      | 1.16                                                                                                                                    | The workflow type is not registered with the dependency injection provider                                                         | Yes |
+| DAPR1302 | Dapr.Workflow | Usage | Warning | 1.16                                                                                                                                    | The workflow activity type is not registered with the dependency injection provider                                                | Yes | 
+| DAPR1401 | Dapr.Actors | Usage            | Warning      | 1.16                                                                                                                                    | Actor timer method invocations require the named callback method to exist on type                                                  | No                 |
+| DAPR1402 | Dapr.Actors | Usage            | Warning      | 1.16                                                                                                                                    | The actor type is not registered with dependency injection                                                                         | Yes                                                                                 |
+| DAPR1403 | Dapr.Actors | Interoperability | Info         | 1.16                                                                                                                                    | Set options.UseJsonSerialization to true to support interoperability with non-.NET actors                                          | Yes                                                                                 |
+| DAPR1404 | Dapr.Actors | Usage            | Warning      | 1.16                                                                                                                                    | Call app.MapActorsHandlers to map endpoints for Dapr actors                                                                        | Yes                                                                                       |
+| DAPR1501 | Dapr.Jobs | Usage            | Warning      | 1.16 |  Job invocations require the MapDaprScheduledJobHandler to be set and configured for each anticipated job on IEndpointRouteBuilder | No                                                                                        |
 
 ## Analyzer Categories
 The following are each of the eligible categories that an analyzer can be assigned to and are modeled after the 
-standard categories used by the.NET analyzers:
+standard categories used by the .NET analyzers:
 - Design
 - Documentation
 - Globalization