docs: address readability feedbacks

Author: heitorlessa

docs/content/utilities/batch.mdx

@@ -15,12 +15,17 @@ The SQS batch processing utility provides a way to handle partial failures when
 
 **Background**
 
-When using SQS as a Lambda event source mapping, functions can be triggered with a batch of messages from SQS. If the Lambda function fails when processing the batch,
-all messages in the batch will be returned to the queue. With this utility, messages within a batch are handled individually - only messages that were not successfully processed
-are returned to the queue. More details on how Lambda works with SQS can be found in the [AWS documentation](https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html).
+When using SQS as a Lambda event source mapping, Lambda functions are triggered with a batch of messages from SQS.
+
+If your function fails to process any message from the batch, the entire batch returns to your SQS queue, and your Lambda function is triggered with the same batch one more time.
+
+With this utility, messages within a batch are handled individually - only messages that were not successfully processed
+are returned to the queue.
 
 <Note type="warning">
   While this utility lowers the chance of processing messages more than once, it is not guaranteed. We recommend implementing processing logic in an idempotent manner wherever possible.
+  <br/><br/>
+  More details on how Lambda works with SQS can be found in the <a href="https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html">AWS documentation</a>
 </Note><br/>
 
 
@@ -30,14 +35,37 @@ This utility requires additional permissions to work as expected. Lambda functio
 
 ## Processing messages from SQS
 
-There are 2 ways to use this utility for processing SQS messages:
+You can use either **[sqs_batch_processor](#sqs_batch_processor-decorator)** decorator, or **[PartialSQSProcessor](#partialsqsprocessor-context-manager)** as a context manager.
+
+They have nearly the same behaviour when it comes to processing messages from the batch:
+
+* **Entire batch has been successfully processed**, where your Lambda handler returned successfully, we will let SQS delete the batch to optimize your cost
+* **Entire Batch has been partially processed successfully**, where exceptions were raised within your `record handler`, we will:
+    - **1)** Delete successfully processed messages from the queue by directly calling `sqs:DeleteMessageBatch`
+    - **2)** Raise `SQSBatchProcessingError` to ensure failed messages return to your SQS queue
+
+The only difference is that **PartialSQSProcessor** will give you access to processed messages if you need.
+
+## Record Handler
+
+Both decorator and context managers require an explicit function to process the batch of messages - namely `record_handler` parameter.
 
-**With a decorator:**
+This function is responsible for processing each individual message from the batch, and to raise an exception if unable to process any of the messages sent.
 
-Using the `sqs_batch_processor` decorator with your lambda handler function, you provide a `record_handler` which is responsible for processing individual messages. It should raise an exception if
-it is unable to process the record. All records in the batch will be passed to this handler for processing, even if exceptions are thrown. After all messages are processed, any successfully processed
-ones will be deleted from the queue. If there were any messages the `record_handler` couldn't process, `SQSBatchProcessingError` will be raised. You will not have accessed to the _processed_ messages
-within the lambda handler - all processing logic should be performed by the `record_handler` function.
+**Any non-exception/successful return from your record handler function** will instruct both decorator and context manager to queue up each individual message for deletion.
+
+### sqs_batch_processor decorator
+
+When using the this decorator, you need provide a function via `record_handler` param that will process individual messages from the batch - It should raise an exception if it is unable to process the record.
+
+All records in the batch will be passed to this handler for processing, even if exceptions are thrown - Here's the behaviour after completing the batch:
+
+* **Any successfully processed messages**, we will delete them from the queue via `sqs:DeleteMessageBatch`
+* **Any unprocessed messages detected**, we will raise `SQSBatchProcessingError` to ensure failed messages return to your SQS queue
+
+<Note type="warning">
+  You will not have accessed to the <strong>processed messages</strong> within the Lambda Handler - all processing logic will and should be performed by the <code>record_handler</code> function.
+</Note><br/>
 
 ```python:title=app.py
 from aws_lambda_powertools.utilities.batch import sqs_batch_processor
@@ -53,10 +81,11 @@ def lambda_handler(event, context):
     return {"statusCode": 200}
 ```
 
-**With a context manager:**
+### PartialSQSProcessor context manager
+
+If you require access to the result of processed messages, you can use this context manager.
 
-If you require access to the result of processed messages, you can use the context manager. The result from calling `process()` on the context manager will be a list of
-all the return values from your `record_handler` function.
+The result from calling `process()` on the context manager will be a list of all the return values from your `record_handler` function.
 
 ```python:title=app.py
 from aws_lambda_powertools.utilities.batch import PartialSQSProcessor
@@ -73,8 +102,8 @@ def lambda_handler(event, context):
 
     processor = PartialSQSProcessor()
 
-    with processor(records, record_handler):
-        result = processor.process()  # Returns a list of all results from record_handler
+    with processor(records, record_handler) as proc:
+        result = proc.process()  # Returns a list of all results from record_handler
 
     return result
 ```
@@ -130,19 +159,19 @@ def lambda_handler(event, context):
 
 ## Suppressing exceptions
 
-If you want to disable the defualt behavior where `SQSBatchProcessingError` is raised if there are any errors, you can pass the `suppress_exception` argument.
+If you want to disable the default behavior where `SQSBatchProcessingError` is raised if there are any errors, you can pass the `suppress_exception` boolean argument.
 
-<Note type="warning">
-If your Lambda function executes successfully and returns a response, all messages in the batch will be deleted from the queue.
-</Note><br/>
+**Within the decorator**
 
 ```python:title=app.py
 ...
 @sqs_batch_processor(record_handler=record_handler, config=config, suppress_exception=True)  # highlight-line
 def lambda_handler(event, context):
     return {"statusCode": 200}
 ```
-or
+
+**Within the context manager**
+
 ```python:title=app.py
 processor = PartialSQSProcessor(config=config, suppress_exception=True)  # highlight-line
 
@@ -154,7 +183,9 @@ with processor(records, record_handler):
 
 You can create your own partial batch processor by inheriting the `BasePartialProcessor` class, and implementing `_prepare()`, `_clean()` and `_process_record()`.
 
-All processing logic is handled by `_process_record()` whilst `_prepare()` and `clean()` take care of doing a setup/teardown of the processor, being called at start/end of processor's execution, respectively.
+* **`_process_record()`** - Handles all processing logic for each individual message of a batch, including calling the `record_handler` (self.handler)
+* **`_prepare()`** - Called once as part of the processor initialization
+* **`clean()`** - Teardown logic called once after `_process_record` completes
 
 You can then use this class as a context manager, or pass it to `batch_processor` to use as a decorator on your Lambda handler function.
 
@@ -165,19 +196,18 @@ from random import randint
 
 from aws_lambda_powertools.utilities.batch import BasePartialProcessor, batch_processor
 import boto3
+import os
 
-def record_handler(record):
-    return randint(0, 100)
-
+table_name = os.getenv("TABLE_NAME", "table_not_found")
 
 class MyPartialProcessor(BasePartialProcessor):
     """
-    Process a record and stores successful results at a DDB Table
+    Process a record and stores successful results at a Amazon DynamoDB Table
 
     Parameters
     ----------
     table_name: str
-        Table name to write results
+        DynamoDB table name to write results to
     """
 
     def __init__(self, table_name: str):
@@ -203,9 +233,10 @@ class MyPartialProcessor(BasePartialProcessor):
     def _process_record(self, record):
         # It handles how your record is processed
         # Here we're keeping the status of each run
+        # where self.handler is the record_handler function passed as an argument
         # E.g.:
         try:
-            result = self.handler(record)
+            result = self.handler(record) # record_handler passed to decorator/context manager
             return self.success_handler(record, result)
         except Exception as exc:
             return self.failure_handler(record, exc)
@@ -217,7 +248,10 @@ class MyPartialProcessor(BasePartialProcessor):
         return entry
 
 
-@batch_processor(record_handler=record_handler, processor=MyPartialProcessor("dummy-table"))
+def record_handler(record):
+    return randint(0, 100)
+
+@batch_processor(record_handler=record_handler, processor=MyPartialProcessor(table_name))
 def lambda_handler(event, context):
     return {"statusCode": 200}
 ```