improve mq docs

content/en/user-guide/aws/mq/index.md

@@ -1,31 +1,51 @@
 ---
-title: "Amazon MQ"
-linkTitle: "Amazon MQ"
-description: >
-  Get started with Amazon MQ on LocalStack
+title: "MQ"
+linkTitle: "MQ"
+description: Get started with MQ on LocalStack
 ---
 
 ## Introduction
-Amazon MQ is a fully managed service for open-source message brokers.
-Basic support is included in LocalStack, please refer to the [feature-coverage]({{< ref "feature-coverage" >}}) for more information.
 
-LocalStack supports MQ via the Pro/Team offering, allowing you to use the MQ APIs in your local environment. The supported APIs are available on our [API Coverage Page](https://docs.localstack.cloud/references/coverage/coverage_mq/), which provides information on the extent of MQ integration with LocalStack.
+MQ is a managed message broker service offered by Amazon Web Services (AWS). It facilitates the exchange of messages between various components of distributed applications, enabling reliable and scalable communication. AWS MQ supports popular messaging protocols like MQTT, AMQP, and STOMP, making it suitable for a wide range of messaging use cases.
+
+LocalStack supports MQ via the Pro/Team offering, allowing you to use the MQ APIs to implement pub/sub messaging, request/response patterns, or distributed event-driven architectures in your local environment. The supported APIs are available on our [API Coverage Page](https://docs.localstack.cloud/references/coverage/coverage_mq/), which provides information on the extent of MQ integration with LocalStack.
 
 ## Getting started
-In the following, we outline basic MQ usage.
-Assuming you have [`awslocal`]({{< ref "aws-cli" >}}) installed, you can try the following commands:
+
+This guide is designed for users new to MQ and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local)  wrapper script.
+
+Start your LocalStack container using your preferred method. We will demonstrate how to create an MQ broker and send a message to a sample queue.
+
+### Create a broker
+
+You can create a broker using the [`CreateBroker`](https://docs.aws.amazon.com/amazon-mq/latest/api-reference/brokers.html#brokerspost) API. Run the following command to create a broker named `test-broker` with the following configuration:
 
 {{< command >}}
-$ awslocal mq create-broker --broker-name test-broker --deployment-mode SINGLE_INSTANCE --engine-type ACTIVEMQ --engine-version='5.16.6' --host-instance-type 'mq.t2.micro' --auto-minor-version-upgrade --publicly-accessible --users='{"ConsoleAccess": true, "Groups": ["testgroup"],"Password": "QXwV*$iUM9USHnVv&!^7s3c@", "Username": "admin"}'
+$ awslocal mq create-broker \
+    --broker-name test-broker \
+    --deployment-mode SINGLE_INSTANCE \
+    --engine-type ACTIVEMQ \
+    --engine-version='5.16.6' \
+    --host-instance-type 'mq.t2.micro' \
+    --auto-minor-version-upgrade \
+    --publicly-accessible \
+    --users='{"ConsoleAccess": true, "Groups": ["testgroup"],"Password": "QXwV*$iUM9USHnVv&!^7s3c@", "Username": "admin"}'
+<disable-copy>
 {
     "BrokerArn": "arn:aws:mq:us-east-1:000000000000:broker:test-broker:b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545",
     "BrokerId": "b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545"
 }
+</disable-copy>
 {{< / command >}}
 
-Using the Describe-Broker endpoint, it is possible to get more detailed information about an instance. The ConsoleURL is especially handy, because it provides the address to the web console (accessible via the user "admin" and password "admin").
+### Describe the broker
+
+You can use the [`DescribeBroker`](https://docs.aws.amazon.com/amazon-mq/latest/api-reference/brokers.html#brokersget) API to get more detailed information about the broker. Run the following command to get information about the broker we created above:
+
 {{< command >}}
-$ awslocal mq describe-broker --broker-id b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545
+$ awslocal mq describe-broker --broker-id
+<disable-copy> 
+b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545
 {
     "BrokerArn": "arn:aws:mq:us-east-1:000000000000:broker:test-broker:b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545",
     "BrokerId": "b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545",
@@ -46,20 +66,29 @@ $ awslocal mq describe-broker --broker-id b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545
     "HostInstanceType": "mq.t2.micro",
     "Tags": {}
 }
+</disable-copy>
 {{< / command >}}
 
-Since the broker is now actively listening, we can send a message to a sample queue using curl.
+### Send a message
+
+Now that the broker is actively listening, we can use curl to send a message to a sample queue. Run the following command to send a message to the `orders.input` queue:
+
 {{< command >}}
 $ curl -XPOST -d "body=message" http://admin:admin@localhost:4513/api/message\?destination\=queue://orders.input
 {{< / command >}}
 
 ## Examples
-Simple demo application illustrating the use of MQ using LocalStack: [Demo](https://github.com/localstack/localstack-pro-samples/tree/master/mq-broker).
+
+The following code snippets and sample applications provide practical examples of how to use MQ in LocalStack for various use cases:
+
+- [Demo application illustrating the use of MQ with LocalStack](https://github.com/localstack/localstack-pro-samples/tree/master/mq-broker)
 
 ## Limitations
-Only basic functionality is supported right now, main limitations are the following:
-* Only ActiveMQ (version 5.16.6) is supported
-* Users are not actively enforced (but needed to make proper calls)
-* While it is possible to create configurations, they are not actively enforced in a broker
-* Persistence and Cloud Pods are not supported
-* Limited API coverage
+
+Currently, our MQ emulation offers only fundamental capabilities, and it comes with certain limitations:
+
+- **ActiveMQ Version Limitation:** Presently, only ActiveMQ version 5.16.6 is supported.
+- **IAM User Management:** IAM Users are not actively enforced, although they are necessary for making correct calls within the system.
+- **Configuration Enforcement:** While it is feasible to create configurations, they are not actively enforced within the broker. 
+- **Persistence and Cloud Pods:** LocalStack does not provide support for Persistence and Cloud Pods at this time.
+- **API Coverage:** Please note that there is limited API coverage available as part of the current emulation capabilities.