docs: documentation improvements (#263)

Recommendations to improve the docs from Pete

Co-authored-by: Pete Vielhaber <95773776+petevielhaber@users.noreply.github.com>
Signed-off-by: Fabio <Pinheiro>

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 ### Description: 
 Summarize the changes you're submitting in a few sentences, including Jira ticket ATL-xxxx if applicable.
-Link to any discussion, related issues and bug reports to give the context to help the reviewer understand the PR.
+Link to any discussion, related issues, and bug reports to give the context and help the reviewer understand the PR.
 
 ### Alternatives Considered (optional): 
 Link to existing ADR (Architecture Decision Record), if any. If relevant, describe other approaches explored and the selected approach. Documenting why the methods were not selected will create a knowledge base for future reference, helping prevent others from revisiting less optimal ideas.

Mediator-Error_Handling.md

@@ -25,9 +25,9 @@ This table defines the expected behavior of the mediator in different scenarios
 |             |                |                        |
 | Scenario M1 | M1B            | -                      |
 | Scenario M2 | M2B            | -                      |
-| Scenario M3 | Fallback G4    | M3B                    |
+| Scenario M3 | M3B            | -                      |
 | Scenario M4 | M4B            | -                      |
-| Scenario M5 | M5A            | M5B [#145]             |
+| Scenario M5 | M5B [#145]     | -                      |
 
 ### Scenarios Description
 
@@ -98,10 +98,9 @@ This table defines the expected behavior of the mediator in different scenarios
 
 In the Atala PRISM Mediator, when an issue arises, we undertake the following steps:
 * Log the error.
-* Dispatch a problem report as outlined in the aforementioned table.
+* Dispatch a problem report as outlined in the table above.
 * Record the problem report and error information in the database.
-Every one of these steps should be traceable back to the initial call via a XRequestID,
-and by the MsgID (which is the SHA-251 hash of the encrypted message).
+Every one of these steps should be traceable back to the initial call via an `XRequestID`, and by the MsgID (the SHA-251 hash of the encrypted message).
 This procedure will enhance Level 3 support and debugging capabilities. (For [ATL-4147](https://input-output.atlassian.net/browse/ATL-4147))
 
 [TODO optional] Would be nice to propose a list/table of new tokens to the protocol specs:

README.md

@@ -18,14 +18,14 @@ graph LR
   M--pickup-->D((Reciever))
 ```
 
- - **CI** automates builds and tests all pushes to the main branch as well as all PRs created.
- - **Scala Steward** automates the creation of pull requests for libraries with updated dependencies, saving maintainers time and effort. It can also help ensure that libraries are kept up-to-date, improving their reliability and performance.
+ - **CI** automates builds and tests that push to the main branch for all PRs created.
+ - **Scala Steward** automates the creation of pull requests for libraries with updated dependencies, saving maintainers time and effort. It can also help keep libraries updated, improving their reliability and performance.
 
 ---
 
 **#atala-mediator on Discord:**
 
-For the fastest answers, join the [#atala-mediator][Link-Discord] channel in the official Atala Discord and ask your questions, or just chat with other Atala developers and pioneers!
+For the fastest answers, join the [#atala-mediator][Link-Discord] channel in the official Atala Discord and ask your questions, or chat with other Atala developers and pioneers!
 
 
 **More documentation:**
@@ -152,14 +152,15 @@ To set up the mediator storage (MongoDB):
 
 ## Run
 
-This DIDComm Mediator is composed of two elements, a backend service, and a database.
-The backend service is a JVM application and the database used is MongoDB.
-The backend service is also a web service that has a single-page application that will give the final user an invitation page.
+The DIDComm Mediator comprises two elements: a backend service and a database.
+The backend service is a JVM application, and the database used is MongoDB.
+The backend service is also a web service with a single-page application that will give the final user an invitation page.
+
 
 ### Run locally
 
-Everything can be run with a single command with Docker compose `docker compose up`.
-For a specific version, you can setup with `MEDIATOR_VERSION` like `MEDIATOR_VERSION=0.9.2-SNAPSHOT docker compose up`.
+Everything runs with a single Docker compose command: `docker compose up`.
+You can set up a specific version with `MEDIATOR_VERSION` like `MEDIATOR_VERSION=0.9.2-SNAPSHOT docker-compose up`.
 
 #### Troubleshooting
 
@@ -174,7 +175,7 @@ You can try to run with `NODE_OPTIONS=--openssl-legacy-provider` to use the lega
 
 ### MongoDB In the cloud
 
-Using the Mongodb from cloud-like MongoDB Atlas.
+Use the Mongodb from the cloud like MongoDB Atlas.
 You will need to create the table and indexes before starting the backend service. See the file `initdb.js`.
 
 ## Deploy

logging.md

@@ -1,10 +1,10 @@
 # Logging
 
 We want traceability from HTTP calls.
-- Each HTTP call needs to generate a call ID (preferable on the proxy). This ID must be should be pass to the scope of the ZIO application. So every log will mention this ID. This ID must also be returned to the user as a HTTP header.
-- In case of errors and problem reports those IDs can be use by the user to get support.
+- Each HTTP call needs to generate a call ID (preferably on the proxy). The ID must be within the scope of the ZIO application. So, every log will mention this ID. This ID must return to the user as an HTTP header.
+- In case of errors and problem reports, the user can use those IDs to get support.
 
-Level 3 support can be provided to user during the logging retention policies. We user need to provide the value in the header `X-Request-Id` to get this support.
+A user can receive Level 3 support during the logging retention policies. The user needs to provide the value in the header `X-Request-Id` to get this support.
 
 ## Annotates
 
@@ -17,12 +17,12 @@ Here is the list of annotations and their meaning that we currently have:
 
 ## Code
 
-To have a concise code we have created a Middleware that modifies the Annotations in the Scope before each execution of that endpoint, to include the trace ID of the request.
+To have a concise code, we have created a middleware that modifies the annotations in the scope before each execution of that endpoint and includes the trace ID of the request.
 See code in file `TraceIdMiddleware` (`mediator/src/main/scala/io/iohk/atala/mediator/TraceIdMiddleware.scala`).
 
 ## Logging Backend
 
-We use the Simple Logging Facade for Java (SLF4J) API to call the logging backend is determined at runtime.
+We use the Simple Logging Facade for Java (SLF4J) API to call the logging backend determined at runtime.
 
 ### Logging Pattern