Developer documentation updates (Azure#40870)

* doc updates

* wording

* Fix spelling and link issues

* Code snippet documentation

---------

Co-authored-by: Josiah Vinson <[email protected]>

Author: jovinson-ms

.vscode/cspell.json

@@ -343,6 +343,7 @@
     "mynewpackage",
     "mypackage",
     "myvault",
+    "myservice",
     "mytable",
     "nazsdk",
     "nbytes",
@@ -391,6 +392,7 @@
     "pyright",
     "pyrightconfig",
     "parameterizing",
+    "pypirc",
     "pyrit",
     "pytyped",
     "pytz",

doc/dev/code_snippets.md

@@ -2,8 +2,8 @@
 
 All code snippets in README should be up to date and runnable. And we want to have single source of truth hence we only need to maintain one copy. To achieve it, we want to have:
 
-- [Store samples in samples folder and setup the pipeline to run them to make sure no sample is broken](#create-samples)
-- [In README, refer the code snippet from the samples](#refer-samples)
+- [Define snippet definitions in the samples folder](#create-samples)
+- [In README, refer to the code snippets from the samples](#refer-samples)
 - [Run `python_snippet_updater.py` to keep them in sync](#python_snippet_updater-tool)
 
 ## Create samples
@@ -29,35 +29,38 @@ https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/samp
 
 Instead of copying the code snippet into README which is hard to maintain and validate, we add reference to the sample snippet in README. We use the annotation `\<!-- SNIPPET:file_name.snippet_name-->` to refer the code snippet in README file.
 
-It is like:
-
-`\<!-- SNIPPET:test_example_async.asyncio -->`
+If you have a file in `samples\text_example_async.py` with a snippet named `asyncio`, you can reference it in your README like:
 
+````markdown
+<!-- SNIPPET:test_example_async.asyncio -->
 ```python
-from azure.core.pipeline.transport import AsyncioRequestsTransport
-
-async with AsyncPipeline(AsyncioRequestsTransport(), policies=policies) as pipeline:
-    response = await pipeline.run(request)
 ```
+<!-- END SNIPPET -->
+````
 
-`\<!-- END SNIPPET -->`
-
-**Note:** you need to make sure there is
-
-\```python
-
-\```
-
-within `\<!-- SNIPPET:` & `\<!-- END SNIPPET -->` in README.MD to make the annotation valid.
+> Make sure you include a Python code fence within the snippet reference!
 
 ## Run python_snippet_updater tool
 
 ```powershell
 python <azure-sdk-for-python>/tools/azure-sdk-tools/ci_tools/snippet_update/python_snippet_updater.py <path_to_the_service>
 ```
 
-The script scans the snippets in samples folder and auto replace the snippets in README with the one from samples folder.
+The script scans the snippets in samples folder and populates snippet references in README with the snippet definitions from samples folder.
+
+The example reference above could become:
+
+````markdown
+<!-- SNIPPET:test_example_async.asyncio -->
+
+```python
+from azure.core.pipeline.transport import AsyncioRequestsTransport
+
+async with AsyncPipeline(AsyncioRequestsTransport(), policies=policies) as pipeline:
+    response = await pipeline.run(request)
+```
 
-**NOTE: the snippets in README will be overwritten!**
+<!-- END SNIPPET -->
+````
 
-Now you are all set!
+Once you've run the script, you can commit your changes. Now you are all set!

doc/dev/dev_setup.md

@@ -43,8 +43,7 @@ or execute the various commands available in the toolbox.
 
 5.  Create a .env file to store your secrets.
 
-    The recommended place to store your .env file is one directory higher than the `azure-sdk-for-python` location.
-    This ensures the secrets will be loaded by the interpreter and most importantly not be committed to Git history.
+    The recommended place to store your .env file in the root of the SDK repository, as it will be gitignored.
 
 ## Follow test-running guidance
 

doc/dev/release.md

@@ -1,14 +1,15 @@
 # Release process
 
-### Disclaimer
-This article assumes you have code on `main` that is ready to publish:
-- Version is accurate
-- ChangeLog is updated
-- Readme is accurate, etc.
+## Prerequisites
+First, ensure your code on `main` is ready to publish.
 
-If you don't, and you are working with Management packages, start with this page:
-https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/mgmt/mgmt_release.md
+For management (control plane) packages, start with this page: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/mgmt/mgmt_release.md
 
+For client (data plane) packages, ensure that:
+- The version at `sdk/path-to-your-package/_version.py` has been updated following [these guidelines](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/package_version/package_version_rule.md).
+- The changelog has been updated following [these guidelines](https://azure.github.io/azure-sdk/policies_releases.html#change-logs).
+- Package README has been updated following [these guidelines](https://azure.github.io/azure-sdk/python_documentation.html).
+- Samples have been updated following [these guidelines](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/sample_guide.md).
 
 ## Python Package Index
 

doc/dev/sample_guide.md

@@ -42,6 +42,8 @@ Note that the metadata under `products` must match an existing product slug foun
 
 ## Capturing code snippets in reference documentation
 Code snippets from samples can be captured as [examples][qa_example] in our reference documentation.
+See [code snippets documentation](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/code_snippets.md) for more details on how to define and reference code snippets in Markdown files.
+
 To do this, place `# [START <keyword>]` and `# [END <keyword>]` comments which span the lines you want to show up in the reference documentation example.
 Note that the <keyword> used should be unique across all sync/async samples added to a client library.