Addressing Andrea's feedback

Author: leandrodamascena

docs/maintainers.md

@@ -151,33 +151,37 @@ Some examples using our initial and new RFC templates: #92, #94, #95, #991, #122
 
 ### Releasing a new version
 
-!!! note "Only maintainers with write permissions to this repository can trigger the pipeline to release a new version"
+!!! note "Only maintainers with write access to this repository can release a new version"
 
 Releasing a new version is a multi-step process that takes up to 2 hours to complete. Most steps are automated - you provide inputs to trigger the release and monitor progress.
 
 **Prerequisites**: Ensure the commit history in the `develop` branch is up to date, commit messages are semantic, and include their respective area (e.g., `feat(logger): <change>`, `chore(ci): ...`).
 
+<!-- markdownlint-disable MD013 -->
 **Release Steps**:
 
-1. **Run end-to-end tests** and ensure they pass
-2. **Trigger Release v3 workflow** - Run the [`Release v3`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/release-v3.yml) workflow with two inputs: the new Powertools version (check [latest version](https://pypi.org/project/aws-lambda-powertools/)) and the new Lambda Layer version number
+1. **Run [end-to-end tests](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/.github/workflows/run-e2e-tests.yml)** and ensure they pass
+2. **Trigger Release v3 workflow** - Run the [`Release v3`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/release-v3.yml) workflow with two inputs: the new Powertools version (check [latest version](https://pypi.org/project/aws-lambda-powertools/)) and the new Lambda Layer version number. To find the new Lambda Layer version number, go to this [page](https://docs.powertools.aws.dev/lambda/python/latest/#python-313) and increase the version by one (N + 1).
 3. **Monitor the release workflow** - it runs tests, publishes to PyPI, deploys Lambda layers to Beta and Prod environments across all commercial regions, runs canary tests, and updates documentation. If it fails, see the [Re-run partial failed Release workflow](#re-run-partial-failed-release-workflow) section
 4. **Review and merge documentation/version PRs** - two PRs will be created to update documentation and bump version files. Review, approve and merge both (order doesn't matter)
-5. **Deploy GovCloud layers** - Run the [`Layer Deployment (GovCloud)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layer_govcloud.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2. Contact the Powertools team via internal tools if this fails
-6. **Deploy China layers** - Run the [`Layer Deployment (Partitions)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layers_partitions.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2. Contact the Powertools team via internal tools if this fails
+5. **Deploy GovCloud layers** - Run the [`Layer Deployment (GovCloud)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layer_govcloud.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2.
+6. **Deploy China layers** - Run the [`Layer Deployment (Partitions)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layers_partitions.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2.
 7. **Update documentation** - Run the [`Rebuild latest docs`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/rebuild_latest_docs.yml) workflow with `develop` branch and the PyPI package version
 
 Once complete, you can start drafting the release notes to let customers know **what changed and what's in it for them (a.k.a why they should care)**. We have guidelines in the [release notes](#drafting-release-notes) section so you know what good looks like.
 
 #### Re-run partial failed Release workflow
 
-While workflows are designed to be stable, failures can occur during the release process. If the Release v3 workflow fails, you have two recovery options:
+While workflows are designed to be stable, failures can occur during the release process. If the release workflow fails, you have two recovery options:
 
-**Option 1: Re-run failed jobs**
-If layer deployments fail due to CloudFormation errors (we deploy ~600 layers per release and can't control CloudFormation quotas), you can re-run only the failed jobs. This will retry the deployment and typically resolves quota-related issues.
+**Option 1: Re-run failed jobs** The Release v3 pipeline contains several steps, and one of them is `publish_layer`. This step is responsible for building and deploying public Lambda layers. If this step fails due to CloudFormation errors (we deploy approximately 600 layers per release and cannot control CloudFormation quotas), you can re-run only the failed jobs. This will retry the deployment and typically resolves quota-related issues.
+<!-- markdownlint-enable MD013 -->
 
 **Option 2: Re-trigger the entire workflow**
-If the release fails due to workflow modifications or permission issues that prevent re-running failed jobs, trigger the Release v3 workflow again. In this case, check the `Skip publishing to PyPI as it can't publish more than once. Useful for semi-failed releases` option to avoid PyPI publishing conflicts.
+If the release fails due to workflow modifications or permission issues that prevent re-running failed jobs, trigger the Release v3 workflow again.
+
+!!! important "Avoid PyPI errors"
+    Make sure to select `Skip publishing to PyPI` as it can't publish more than once. This is useful for semi-failed releases when rerunning the entire workflow to avoid duplicate publishes
 
 #### Release process visualized