docs(concepts): improve writing style (#3354)

Author: bandantonio

markdown/docs/concepts/application.md

@@ -5,12 +5,12 @@ weight: 23
 
 
 ## What is an application?
-An application is any computer program or a group of them. 
+An _application_ is a computer program or a group of them. 
 
-An application could also be a micro-service, IoT device (sensor), mainframe process, etc. Users may even write applications in different programming languages if they support one of the selected protocols. 
+An application can be a micro-service, IoT (Internet of things) device (for example, a sensor), mainframe process, and more. Users can create applications using various programming languages that support the chosen protocols.
 
 ## Why do we need applications?
-In Event-Driven Architecture (EDA), an application must be a `producer`, a `consumer`, or both. Applications must also use the protocols the server supports if they wish to connect and exchange messages.
+In Event-Driven Architecture (EDA), an application can either be a producer, a consumer, or both. Additionally, if an application wants to connect and exchange messages with the server, it must adhere to the protocols supported by the server.
 
 ### Applications: producers and consumers
 ```mermaid
@@ -20,4 +20,5 @@ flowchart TD
         C --> D[message] 
         D --> F[CONSUMER application]
 ```
-The above diagram describes a message communication traveling through a channel between a **PRODUCER application** and a **CONSUMER application**. 
+
+The diagram above illustrates a message transmission between a Producer application and a Consumer application through a channel.

markdown/docs/concepts/asyncapi-document/index.md

@@ -3,11 +3,11 @@ title: 'Introduction'
 weight: 50
 ---
 
-The AsyncAPI Specification defines a set of fields that can be used in an AsyncAPI document to describe an application's API. The document may reference other files for additional details or shared fields, but it is typically a single, primary document that encapsulates the API description.
+The AsyncAPI Specification defines a set of fields that can be used in an AsyncAPI document to describe an application’s API. While the document may reference other files for additional details or shared fields, it usually serves as a single, primary document that encapsulates the API description.
 
-Furthermore, the AsyncAPI document acts as a communication contract between `receivers` and `senders` within an event-driven system. It specifies the payload content required when a service sends a message and offers clear guidance to the receiver regarding the message's properties.
+Furthermore, the AsyncAPI document acts as a communication contract between receivers and senders within an event-driven system. It specifies the payload content necessary for a service to send a message and provides clear guidance to the receiver about the message's properties.
 
-```YAML
+```yaml
 asyncapi: 3.0.0
 info:
   title: Cool Example
@@ -37,7 +37,5 @@ operations:
 ```
 
 <Remember>
-You might have additional fields depending on the implemented protocol (i.e., MQTT, AMQP, Kafka, etc.). 
-  
-For example, your AsyncAPI document could have additional fields for <a href= "https://github.com/asyncapi/bindings/tree/master/kafka">configuring Kafka bindings</a>.
+Depending on the implemented protocol (such as MQTT, AMQP, Kafka, etc.), you may have additional fields in your AsyncAPI document. For example, for <a href= "https://github.com/asyncapi/bindings/tree/master/kafka">configuring Kafka bindings</a>.
 </Remember>

markdown/docs/concepts/channel.md

@@ -4,12 +4,10 @@ weight: 20
 ---
 
 # What is a channel?
-A `channel` is a mechanism created by the server for the organization and transmission of messages. Users can define channels as a _topic, queue, routing key, path,_  or _subject_ depending on the protocol used.
+A _channel_ is a mechanism created by the server that facilitates the organization and transmission of messages. Depending on the used protocol, users can define channels as a _topic_, _queue_, _routing key_, _path_, or _subject_.
 
 # Why do we need channels?
-Channels play a crucial role in communication between `producers` and `consumers`. A producer can send a message through the channel, and the consumer receives messages from a particular channel. A channel's sole purpose is to ensure the right messages route to the right consumers.
-
-
+Channels are pivotal for establishing communication between producers and consumers. They enable producers to send messages, while consumers receive messages from specific channels. The primary function of a channel is to ensure that the intended messages reach the appropriate consumers.
 
 ```mermaid
 graph LR
@@ -19,4 +17,6 @@ graph LR
     C --> E[Consumer]
     C --> F[Consumer]
 ```
-The diagram above shows the communication between a `producer` and `consumer`, with the producer sending a `message` through the `channel`. The channel then queues the message to the specific consumer.
+
+The diagram above illustrates the communication process between a producer and a consumer. The producer sends a message through the channel, which then queues the message for delivery to the specific consumer.
+The diagram above illustrates the communication process between a producer and multiple consumers. The producer sends a message through the channel, which then queues the message for delivery to the appropriate consumers.

markdown/docs/concepts/consumer.md

@@ -4,12 +4,12 @@ weight: 4
 ---
 
 ## What is a consumer?
-In an Event Driven Architecture (EDA), a consumer is an application that listens for a particular event from a broker and reacts to it.
+A _consumer_ is an application that subscribes to a specific event from a broker and responds accordingly.
 
 ## Why do we need consumers?
-Unlike traditional REST APIs, in EDA, event consumers are not expected to respond immediately on the same connection. In this architecture, a consumer is unaware of the producer or other consumers; all they know is that when a broker sends them an event, it is because they subscribed to it.
+Unlike traditional REST APIs, in Event-Driven Architecture (EDA), event consumers are asynchronous, which means they are not required to respond immediately on the same connection. In this architecture, consumers are unaware of the producers or other consumers. All they know is that when a broker sends them an event, it is because they have subscribed to it.
 
-When you want events processed asynchronously in your application, the consumer plays an important role in completing that event data flow in the event channel.
+When you want your application to process events asynchronously, the consumer plays a crucial role in completing the event data flow through the event channel.
 
 ```mermaid
 flowchart LR
@@ -26,7 +26,8 @@ flowchart LR
     end
 ```
 
-The above diagram depicts a sample flow of events from `producer` to `broker` to `consumer`. In this instance, the `producer` publishes two events _(A and B)_ and sends them to the `broker`. Then each `consumer` subscribes to receive those events.
+The diagram above illustrates a sample flow of events from the `producer` to the `broker` to the `consumers`. In this scenario, the `producer` publishes two events _(A and B)_ and sends them to the `broker`. Subsequently, each `consumer` subscribes to receive those events.
+
 <Remember>
 <b>Subscribers</b> can also be <a href="https://www.asyncapi.com/docs/concepts/producer">producers</a>.
 </Remember>

markdown/docs/concepts/index.md

@@ -5,9 +5,9 @@ weight: 1
 
 import ContributionNotes from '@/assets/docs/fragments/contribution-notes.md';
 
-## Concepts: Define AsyncAPI features and capabilities
+## Concepts
 
-Welcome to AsyncAPI **Concepts**! Our Concepts section will define the concepts of AsyncAPI features and capabilities.
+Welcome to AsyncAPI **Concepts**! This section defines AsyncAPI features and capabilities.
 
 <Remember>
 

markdown/docs/concepts/message.md

@@ -4,8 +4,9 @@ weight: 30
 ---
 
 ## What is a message?
-A `message` is a communication asset used to transmit or exchange information from a sender to the receiver through `channels`. A single `message` can be consumed by multiple independent receivers and can also be defined as an _event_ or _command_. The sender includes a payload of data (that has been serialized into an appropriate format, e.g., JSON, XML, binary, etc.) that needs to be processed by the receiver. It may also include metadata; information that describes the message itself. This metadata is often known as _headers_ or _properties_.
+A _message_ is a communication asset that transmits or exchanges information from a sender to the receiver through channels.
 
+One message can also be defined as an event or command and can be consumed by multiple independent receivers. The sender encodes a payload of data (serialized into a suitable format, such as JSON, XML, binary, or others) that requires processing by the receiver. Additionally, the message may include _metadata_, which is information that describes the message itself. This metadata is commonly referred to as _headers_ or _properties_.
 
 ``` mermaid
 graph LR
@@ -17,11 +18,10 @@ A{{sender application}} --> b --> C{{receiver application}}
   
 ```
 
-In the diagram above, the sender application transmits a `message` to the receiver application.
+The diagram above illustrates how a sender application transmits a message through a channel to a receiver application, demonstrating the basic flow of message-based communication.
 
 ## Messages vs Events
-A `message` carries information from one application to the other, while an `event` is a message that provides details of something that has already occurred. One important aspect to note is that depending on the type of information a `message` contains, it can fall under an _event_, _query_, or _command_. 
-*See the diagram below.*
+A **message** conveys information between applications, while an **event** is a message that provides details of something that has already occurred. A crucial aspect to note is that depending on the type of information a message carries, it can either be an event, query, or command. Check the diagram below.
 
 ``` mermaid
 graph TD
@@ -32,4 +32,4 @@ graph TD
     C --> E(Command)
 ```
 
-Overall, `events` are `messages` but not all `messages` are `events`.
+Summing up, events are messages, but not all messages are events.

markdown/docs/concepts/producer.md

@@ -4,24 +4,26 @@ weight: 3
 ---
 
 ## What is a Producer? 
-A producer is an application that senses state changes (events) and publishes those events as messages. An event indicates a state change or update triggered by a user's/device's action. 
+A _producer_ is an application that detects state changes (_events_) and publishes these events as messages. An event signifies a state change or update triggered by a user’s or device’s action.
 
 The following are sample events:
-* Placing an item in a shopping cart on an e-commerce website.
+* Adding an item to a shopping cart on an e-commerce website.
 * Clicking the subscribe button on a YouTube channel.
-* A temperature change in a sensor.
+* Detecting a temperature change using a sensor.
+
 
 ## Why do we need Producers? 
-One of the core concepts of event-driven architecture is the publish/subscribe communication model. Producers are publishers in this model; they're the first logical layer responsible for distributing messages to the broker so that others can subscribe to receive messages.
+The publish/subscribe communication model is one of the core concepts of event-driven architecture. In this model, producers are publishers, acting as the first logical layer responsible for distributing messages to the broker, enabling others to subscribe and receive these messages.
 
 ```mermaid
 flowchart TD
     a[Producer]-- Message 1 --->d[(Broker)]
     d -- Message 1 --->g[Consumer]
 ```
-The diagram above depicts the communication between a **producer** publishing events to a specific channel in a **broker** and a **consumer** subscribed to the same channel.
 
-In some cases, an entity can be both a producer publishing messages to a specific channel in the broker and a consumer subscribing to messages from a different channel in the broker.
+The diagram above illustrates the communication flow between a producer who publishes events to a specific channel in a broker and a consumer who subscribes to the same channel.
+
+In some cases, an entity can simultaneously function as both a producer, publishing messages to a specific channel in the broker, and a consumer, subscribing to messages from a different channel in the broker.
 
 ```mermaid
 flowchart LR
@@ -31,4 +33,4 @@ flowchart LR
     c -- Message 2 ---> d[Consumer]
 ```
 
-In the diagram above, we see a producer publishing messages to a specific channel and a consumer subscribing to messages from that channel. We also have a second producer who publishes to one channel, but subscribes to messages from another.
+In the diagram above, there is a producer publishing messages to a specific channel and a consumer subscribing to messages from that channel. Also, there is a second producer publishing to one channel and subscribing to messages from another channel.

markdown/docs/concepts/protocol.md

@@ -5,7 +5,7 @@ weight: 25
 
 
 ## What is a protocol?
-A protocol is a set of rules that specifies how information is exchanged between applications and/or servers.
+A _protocol_ is a set of rules that governs the exchange of information between applications and/or servers.
 
 Protocol examples:
 * [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
@@ -14,7 +14,7 @@ Protocol examples:
 * [MQTT](https://mqtt.org/)
 
 ## Why do we need protocols?
-Whenever a producer detects a state change (events) and publishes those events as messages, a protocol carries those messages to the channel and then to a consumer. Protocol plays a vital role in message transmission.
+Protocols play a crucial role in message transmission. Whenever a producer detects a state change (events) and publishes those events as messages, a protocol carries those messages to the channel and then to the consumer.
 
 ```mermaid
 sequenceDiagram
@@ -23,8 +23,8 @@ sequenceDiagram
     Publisher->>+Publisher: Delete(Msg)
 ```
 
-The diagram above depicts the message exchange flow from `producer` to `broker` to `consumer` using the MQTT protocol with QoS0 (quality of service 0). This means that information exchanged from `producer` to `broker` to `consumer` is delivered at most once.
+The diagram above illustrates the message exchange flow from `producer` to `broker` to `consumer` using the MQTT protocol with QoS0 (quality of service 0). In other words, the information transferred from the producer to broker to consumer is delivered at most once.
 
-The quality of service information rule is specified on a protocol level. Broker implementations and other involved actors must act accordingly.
+The quality of service information rule is defined at the protocol level. Broker implementations and other involved parties must adhere to this rule.
 
-In AsyncAPI documents, all protocol-specific details that the application follows can be described using [bindings](/docs/reference/specification/v2.5.0#definitionsBindings).
+In AsyncAPI documents, all protocol-specific details that the application follows can be described using [bindings](https://www.asyncapi.com/docs/reference/specification/latest#definitionsBindings).

markdown/docs/concepts/server.md

@@ -5,10 +5,10 @@ weight: 2
 
 
 ## What is a server?
-A server represents a messaging broker system where connections and communication between a producer and a consumer are established. Unlike traditional API servers which are dependent on request/response, message broker interactions occur back and forth over different channels.
+A _server_ acts as a _messaging broker_ system, establishing connections and facilitating communication between [_producers_](producer) and [_consumers_](consumer). Unlike traditional API servers that rely on request-response interactions, message broker interactions occur bidirectionally across various channels.
 
 ## What is the purpose of servers?
-Servers play an important role in maintaining a relationship between producers and consumers. When designing and setting up an event-driven application, servers are in charge of delivering asynchronous messages from the producer to the consumers through the use of channels. By integrating different messaging protocols, servers can transmit and exchange messages between clients.
+Servers play a crucial role in establishing a connection between producers and consumers. In the context of designing and setting up an event-driven application, servers are responsible for delivering asynchronous messages from the producer to the consumers through the use of [_channels_](channel). Additionally, servers can integrate various messaging [_protocols_](protocol) to facilitate the transmission and exchange of messages between _clients_.
 
 ### Clients and Server
 ```mermaid
@@ -18,7 +18,7 @@ flowchart TD
     c[Client Mobile] --> b[(server)]
     b --> c 
 ```
-The diagram above describes a bi-directional communication between several **clients** and one **server**. In this case, in your AsyncAPI file, you describe the `server`, and therefore the [`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverObject) holds information about the actual server, including its physical location.
+The diagram above illustrates a bidirectional communication between one server and several clients. In this case, in your AsyncAPI file, you describe the `server`, so the [`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverObject) holds information about the actual server, including its physical location.
 
 
 ### Broker Centric
@@ -35,4 +35,4 @@ flowchart TD
     a2 --> C[consumer2]
 ```
 
-The diagram above shows the *Broker Centric Architecture*. In this case, we created three AsyncAPI files for the `producer`, `consumer1`, and `consumer2`. In these AsyncAPI files, the [`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverObject) provides information about the `broker`, so that API users know where to connect to start receiving or sending messages.
+The diagram above illustrates the Broker-centric Architecture. In this case, there are three AsyncAPI files for the `producer`, `consumer1`, and `consumer2`. In these AsyncAPI files, the [`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverObject) provides information about the `broker`, so that API users know where to connect to start receiving or sending messages.