Improvements for reactive messaging doc

[dmuelle]

we need to review the reactive messaging page and it's children top-to-bottom to make the overall story more concise and clear. There are redundancies among the existing pages that need to be removed or mitigated, and the information should align better with our guides for reactive.

Optimizing asynchronous communication with MicroProfile Reactive Messaging

Intro

• Provide an additional paragraph (~3-5 sentences) to set the context for reactive messaging. Refer to https://openliberty.io/guides/microprofile-reactive-messaging.html#what-youll-learn andn https://openliberty.io/guides/microprofile-reactive-messaging.html#configuring-the-microprofile-reactive-messaging-connectors-for-kafka for context.

• explain that reactive messaging channels in Open Liberty are configured by setting MicroProfile Config properties and link to the reactive msg config properties table.

Configure the Liberty-Kafka connector

• Globally: liberty-kafka connector ---> Liberty-Kafka connector, except in code examples
• "By configuring a MicroProfile application as shown in the example, to connect to a Kafka broker at myKafkaBroker:9092 for messaging. " this is a sentence fragment, replace with a complete sentence. Refer to https://openliberty.io/guides/microprofile-reactive-messaging.html#configuring-the-microprofile-reactive-messaging-connectors-for-kafka to provide a better descritpion of what the code example shows.
• "To integrate Kafka into your application environment by using Open Liberty, choose one of the following methods based on your requirement:" rewrite this sentence to be more direct. Add some information to help the user choose the best option without having to read both of them- what are the reasons you might choose each option?

Sending and receiving messages among applications by using connectors

This section is really just a more detailed version of step 2. Instead of a separate section, integrate this information into step 2. Look for opportunities to remove any redundancies. So step 2 should show the minimal config, as it does now, and then detail common configuration options that are discussed in this section.

Troubleshooting

Im not sure this section is even needed- can this information be integrated into other sections of the page? Eg group.id shows up in the examples, Multiple Reactive Messaging applications using the same Kafka server is discussed in the shared libraries section.

Liberty-Kafka connector options and channel properties

• the distinction btwn incoming and outgoing should be more clear on the page. Create separate sections
• What is a property and what is an attribute? Are they the same thing? It's not clear.
• provide links to and from this page to the MP config properties table for reactive messaging.

Kafka connector security configuration

--> Liberty-Kafka connector security configuration

For configuring the Kafka connector and security in Open Liberty, you can focus on the distinction between channel-specific and connector-wide properties for tailored messaging behavior.
--->
You can configure security for reactive messaging channels at both the channel level and the connector level.

For security, Open Liberty supports multiple authentication methods:

I think these are protocols, not auth methods. And "For security" seems redundant. Try to revise this sentence to describe what is supported and what its for.

To make sure of secure communication with Kafka brokers, you can set the appropriate security properties within the microprofile-config.properties file, facilitating the support of any of the authentication methods.

I think this one needs revision too. I know "make sure" was probably a way to get around saying "ensure", which acrolinx flags, but it's awkward here. The whole sentence can be more direct.

Using Open Liberty’s support for multiple authentication methods, including SSL, SASL/PLAIN, and mTLS, enhances the security of data in transit and ensures the authentication of both clients and servers.

Does the user configure multiple methods? I dont think the conclusion paragraph here is really adding anything

[ramkumar-k-9286]

Hi David @dmuelle

Incorporated comments.

Draft links:
https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/liberty-kafka-connector.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/liberty-kafka-connector-channel-properties.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/liberty-kafka-connector-config-security.html

Regards,
Ramkumar

[dmuelle]

Peer review

Hi Ram- this is looking much better. Just a few suggestions.

Optimizing asynchronous communication with MicroProfile Reactive Messaging

The intro paragraph you added does a great job of setting the context and identifying the value for users. However- it's still a bit wordy. Try to revise it to use more direct language, with more concise sentences that use fewer words in fewer clauses. Also, try to avoid using expletive clauses with no clear referent ("It is..."). For example:

In highly distributed and event-driven application architectures, it is critical to manage data transfer between system components in a nonobstructive and responsive manner. Reactive messaging patterns make it possible by enabling applications to send, receive, and process messages asynchronously.

--->

Highly distributed and event-driven application architectures need to manage data transfer between system components responsively. Reactive messaging patterns enable applications to send, receive, and process messages asynchronously.

There's also at least one typo in the paragraph.

---

I'd recommend moving the first sentence of the next section to be the 2nd to last sentence of the introduction, eg

The Liberty-Kafka connector enables applications to send and receive messages from an Apache Kafka broker. It uses MicroProfile Reactive Messaging standards for robust, asynchronous communication in microservices architectures. The following section describes how to intergrate MicroProfile Reactive Messaging with Apache Kafka to send messages within and between applications.

Configure the Liberty-Kafka connector

This is a sentence fragment- revise to be a complete sentence:

By configuring a MicroProfile application as shown in the example, to connect to a Kafka broker at myKafkaBroker:9092 for messaging.

2. Configuring microservices for Kafka messaging with Liberty-Kafka connector

Revise to remove expletive "it is" clause:

To facilitate communication among applications, it is essential to configure microservices to send and receive messages through Kafka topics.

---

The incoming section doesn't provide any explanation for the deserializer proeprties- were these previously in the doc? They should be defined or explained somehow.

---

Revise to use active voice:

Similarly, for sending messages to a Kafka topic, an outgoing channel must be configured by using the Liberty-Kafka connector.

---

Run acrolinx here and fix error:

By setting up channels as demonstrated, you connect message channels directly to Kafka, offering precise control over the messaging channels. This enhances your application’s scalability and robustness by efficiently managing messages, whether incoming or outgoing.

---

Combine the two "For more information... " sentences, use a bulleted list if needed.

3. Include Kafka client libraries

The bulleted list in the intro explains how you would want to use a shared library but it should tell you why, so the user can make an informed decision about which method to use.

---

Alternatively, you can integrate Kafka client libraries as a shared resource within the Open Liberty server.

Liberty-Kafka connector options and channel properties

I think we need to rethink this page.

• This page is still using "properties" and "attributes" interchangeably but they are two different things.

• the incoming/outgoing tables on the page contain the exact same properties except for unack/fastack.

• But the description of context.service is different in each table.. without reference to incoming/outgoing... doesn't make sense. And the only explanation for the attribute is for outgoing... does it apply to incoming?

• we shouldn't say " the concurrent-x.y feature ", use OL feature macros instead

Managing incoming channels with Liberty-Kafka connector properties

The intro paragraph here is not specific to incoming properties but just repeats the general info from the page intro.

Needs an introductory sentence for any tables though, for a11y purposes.

Kafka connector security configuration

To secure communication with Kafka brokers, set the necessary security properties in the microprofile-config.properties file to support various authentication protocols.

Does one server support multiple protocols? Im not sure but this sounds like yes. Need to confirm whether thats the case and revise as needed.

Secure Sockets Layer (SSL)

mention after the example that it configures and truststore location and password that are required for a secure connection. Also- does this section apply to TLS or just SSL? We should clarify as SSL is technically deprecated, though the term is still widely used.

Mutual TLS (mTLS)

mp.messaging.connector.liberty-kafka.bootstrap.servers=SSL\://kafka-boostrap-server\:39647
mp.messaging.connector.liberty-kafka.security.protocol=SSL
mp.messaging.connector.liberty-kafka.ssl.truststore.location=kafka-truststore.jks
mp.messaging.connector.liberty-kafka.ssl.truststore.password=kafka-teststore
mp.messaging.connector.liberty-kafka.ssl.truststore.location=kafka-truststore.jks

Why is the truststore location specified twice?

[ramkumar-k-9286]

Hi David @dmuelle

Incorporated most of the comments.

Draft links:
https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/liberty-kafka-connector.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/liberty-kafka-connector-config-security.html

I have not done the same for :
https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/liberty-kafka-connector-channel-properties.html
I had some doubts. thought will discuss and incorporate those.

Regards,
Ramkumar

[dmuelle]

This paragraph could still be more concise:

Highly distributed and event-driven application architectures need to manage data transfer between system components responsively. Reactive messaging patterns enable applications to send, receive, and process messages asynchronously. By decoupling system components, this method enhances scalability and resilience. Open Liberty incorporates this paradigm with its MicroProfile Reactive Messaging support. By using MicroProfile Config properties to configure reactive messaging channels in Open Liberty, it is possible to facilitate the administration and specification of how your applications interact with message brokers like Kafka. By configuring this setting, you can precisely tailor the behavior of reactive messaging to the requirements of your application, which facilitates streamlined data processing and communication. For more information, see MicroProfile Config properties for MicroProfile Reactive Messaging.

--->

Reactive messaging patterns enhance scalability and resilience by enabling applications to send, receive, and process messages asynchronously. Open Liberty incorporates this paradigm with its MicroProfile Reactive Messaging support. You can use MicroProfile Config properties to configure reactive messaging channels in Open Liberty and control how your applications interact with message brokers like Kafka. By configuring this setting, you can precisely tailor the behavior of reactive messaging to the requirements of your application. For more information, see MicroProfile Config properties for MicroProfile Reactive Messaging.

---

THere's no instruction to enbale the reactive messaging feature, though you can't use RM without it. This should be step 1

---

The application is able to can send and receive messages through Kafka, facilitating which facilitates event-driven communication.

---

Although Acrolinx doesn't flag it- this is a sentence fragment:

Offering precise control over the messaging channels, enhancing your application’s scalability and robustness by efficiently managing messages, whether incoming or outgoing.

---

For more information:---> For more information, see the following resources:

---

3. Include Kafka client libraries
   use the plus symbol after each item in the bulleted list to add a new line between the title and description

---

[dmuelle]

Liberty-Kafka connector options and channel properties

• rework intro/shortdesc to remove redunancy and not use links in shortdesc
• in the table, the context.service entry needs to link to the context.service section later in the doc. Also, all references to the "concurrent-x.y feature" or "concurrent feature" should be replaced by ' the Jakarta concurrency feature' with a macro link to the latest feature version.

[ramkumar-k-9286]

Hi

Incorporated comments.

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/liberty-kafka-connector-channel-properties.html

Regards,
Ramkumar