Docs: Style updates for Quarkus and Node.js quick starts (#559)

* docs: style updates for quarkus and nodejs quickstarts

* docs: address peer review feedback

* docs: one more peer review update

Author: jbyrne-redhat

docs/kafka/nodejs-kafka/README.adoc

@@ -93,7 +93,7 @@ ifndef::community[]
 endif::[]
 * You have a Kafka instance in {product-kafka} and the instance is in the *Ready* state. To learn how to create a Kafka instance, see {base-url}{getting-started-url-kafka}[Getting started with {product-long-kafka}].
 * https://github.com/git-guides/[Git^] is installed.
-* You have an IDE such as https://www.jetbrains.com/idea/download/[IntelliJ IDEA^], https://www.eclipse.org/downloads/[Eclipse^], or https://code.visualstudio.com/Download[VSCode^].
+* You have an IDE such as https://www.jetbrains.com/idea/download/[IntelliJ IDEA^], https://www.eclipse.org/downloads/[Eclipse^], or https://code.visualstudio.com/Download[Visual Studio Code^].
 * https://nodejs.org/en/download/[Node.js 14^] is installed. The https://github.com/blizzard/node-rdkafka[node-rdkafka^] client can't run on later versions.
 
 NOTE: The example Node.js application in this quick start uses the https://kafka.js.org/[KafkaJS^] client by default. If you want to use the https://github.com/blizzard/node-rdkafka[node-rdkafka^] client, you must install some development tools locally on your computer or use a container runtime such as Podman or Docker to run a specified container image and configure a development environment. To learn more, see the https://github.com/nodeshift-starters/reactive-example/tree/node-rdkafka#node-rdkafka-and-kafkajs[documentation] for the example Node.js application.
@@ -118,12 +118,11 @@ endif::[]
 == Importing the Node.js sample code
 
 [role="_abstract"]
-For this quick start, you'll use sample code from the _Nodeshift Application Starters_ https://github.com/nodeshift-starters/reactive-example[reactive-example^] repository in GitHub. After you understand the concepts and tasks in this quick start, you can use your own Node.js applications with {product-kafka} in the same way.
+For this quick start, you'll use sample code from the Nodeshift Application Starters https://github.com/nodeshift-starters/reactive-example[reactive-example^] repository in GitHub. After you understand the concepts and tasks in this quick start, you can use your own Node.js applications with {product-long-kafka} in the same way.
 
 .Procedure
 . On the command line, clone the Nodeshift Application Starters https://github.com/nodeshift-starters/reactive-example[reactive-example^] repository from GitHub.
 +
-.Cloning the reactive-example repository
 [source,subs="+attributes"]
 ----
 $ git clone https://github.com/nodeshift-starters/reactive-example.git
@@ -142,15 +141,15 @@ endif::[]
 To enable your Node.js application to access a Kafka instance, you must configure a connection by specifying the following details:
 
 * The bootstrap server endpoint for your Kafka instance
-* The generated credentials for your {product-kafka} service account
+* The generated credentials for your {product-long-kafka} service account
 * The Simple Authentication and Security Layer (SASL) mechanism that the client will use to authenticate with the Kafka instance
 
-In this task, you'll create a new configuration file called `rhoas.env`. In this file, you'll set the required bootstrap server and client credentials as environment variables.
+In this task, you'll create a new configuration file called `rhoas.env`. In the file, you'll set the required bootstrap server and client credentials as environment variables.
 
 .Prerequisites
 ifndef::qs[]
 * You have the bootstrap server endpoint for your Kafka instance. To get the server endpoint, select your Kafka instance in the {product-kafka} web console, select the options menu (three vertical dots), and click *Connection*.
-* You have the generated credentials for your service account. To regenerate the credentials, use the *Service Accounts* page in the {product-kafka} web console to find your service account and update the credentials.
+* You have the generated credentials for your service account. To reset the credentials, use the https://console.redhat.com/application-services/service-accounts[Service Accounts^] page in the *Application Services* section of the Red Hat Hybrid Cloud Console.
 * You've set the permissions for your service account to access the Kafka instance resources. To verify the current permissions, select your Kafka instance in the {product-kafka} web console and use the *Access* page to find your service account permission settings.
 endif::[]
 
@@ -168,8 +167,6 @@ RHOAS_CLIENT_ID=__<client_id>__
 RHOAS_CLIENT_SECRET=__<client_secret>__
 KAFKA_SASL_MECHANISM=plain
 ----
-+
-In the preceding example, replace the values in angle brackets (`< >`) with your own bootstrap server and client credential information.
 ifdef::qs[]
 +
 The values are described as follows:
@@ -197,29 +194,32 @@ endif::[]
 The Node.js application in this quick start uses a Kafka topic called `countries` to produce and consume messages. In this task, you'll create the topic in your Kafka instance.
 
 .Prerequisites
-* You've created a Kafka instance in {product-kafka} and the instance is in the *Ready* state.
+* You've created a Kafka instance in {product-long-kafka} and the instance is in the *Ready* state.
 
 .Procedure
-. In the {product-kafka} web console, go to *Streams for Apache Kafka* > *Kafka Instances* and click the name of the Kafka instance that you want to add a topic to.
-. Click *Create topic* and follow the guided steps to define the topic details. Click *Next* to complete each step and click *Finish* to complete the setup.
+. In the {product-kafka} web console, select *Kafka Instances* and then click the name of the Kafka instance that you want to add a topic to.
+. Select the *Topics* tab.
+. Click *Create topic* and follow the guided steps to define the topic details, as shown in the figure.
 +
 [.screencapture]
 .Guided steps to define topic details
 image::sak-create-countries-topic.png[Image of wizard to create a topic]
++
+You must specify the following topic properties:
 
 * *Topic name*: Enter `countries` as the topic name.
 * *Partitions*: Set the number of partitions for this topic. This example sets the partition to `1` for a single partition. Partitions are distinct lists of messages within a topic and enable parts of a topic to be distributed over multiple brokers in the cluster. A topic can contain one or more partitions, enabling producer and consumer loads to be scaled.
 * *Message retention*: Set the message retention time and size to the relevant value and increment. This example sets the retention time to `7 days` and the retention size to `Unlimited`. Message retention time is the amount of time that messages are retained in a topic before they are deleted or compacted, depending on the cleanup policy. Retention size is the maximum total size of all log segments in a partition before they are deleted or compacted.
 * *Replicas*: For this release of {product-kafka}, the replicas are preconfigured. The number of partition replicas for the topic is set to `3` and the minimum number of follower replicas that must be in sync with a partition leader is set to `2`. Replicas are copies of partitions in a topic. Partition replicas are distributed over multiple brokers in the cluster to ensure topic availability if a broker fails. When a follower replica is in sync with a partition leader, the follower replica can become the new partition leader if needed.
 +
-After you complete the topic setup, the new Kafka topic is listed in the topics table for your Kafka instance. You can now run the Node.js application to start producing and consuming messages.
+After you complete the setup, the new topic appears on the *Topics* page. You can now run the Node.js application to start producing and consuming messages.
 
 .Verification
 ifdef::qs[]
-* Is the `countries` topic listed in the topics table?
+* Does the `countries` topic appear on the *Topics* page?
 endif::[]
 ifndef::qs[]
-* Verify that the `countries` topic is listed in the topics table.
+* Verify that the `countries` topic appears on the *Topics* page.
 endif::[]
 
 [id="proc-running-nodejs-example-application_{context}"]
@@ -230,17 +230,16 @@ After you configure your Node.js application to connect to a Kafka instance, and
 
 In this task, you'll run the following components of the Node.js application:
 
-* A `producer-backend` component that generates random country names and sends these names to the Kafka topic.
-* A `consumer-backend` component that consumes the country names from the Kafka topic.
+* A `producer-backend` component that generates random country names and sends these names to the Kafka topic
+* A `consumer-backend` component that consumes the country names from the Kafka topic
 
 .Prerequisites
 * You've configured the Node.js example application to connect to a Kafka instance.
-* You've created the `countries` Kafka topic.
+* You've created the `countries` topic.
 
 .Procedure
 . On the command line, navigate to the `reactive-example` directory of the repository that you cloned.
 +
-.Navigating to the reactive-example directory
 [source]
 ----
 $ cd reactive-example
@@ -257,21 +256,19 @@ $ npm install
 
 . Run the consumer component.
 +
-.Running the consumer component
 [source]
 ----
 $ node consumer.js
 ----
 +
-You should see the Node.js application run and connect to the Kafka instance. However, because you haven't yet run the producer component, the consumer has no country names to display.
+You see the Node.js application run and connect to the Kafka instance. However, because you haven't yet run the producer component, the consumer has no country names to display.
 +
 If the application fails to run, review the error log in the command-line window and address any problems. Also, review the steps in this quick start to ensure that the application and Kafka topic are configured correctly.
 
 . Open a second command-line window or tab.
 
 . On the second command line, navigate to the `reactive-example` directory of the repository that you cloned.
 +
-.Navigating to the reactive-example directory
 [source]
 ----
 $ cd reactive-example
@@ -288,18 +285,16 @@ $ npm install
 
 . Run the producer component.
 +
-.Running the producer component
 [source]
 ----
 $ node producer.js
 ----
 +
-You should see output like that shown in the example.
+When the producer component runs, you see output like that shown in the following example:
 +
 .Example output from the producer component
 [source]
 ----
-$ node producer.js
 Ghana
 Réunion
 Guatemala
@@ -315,12 +310,11 @@ As shown in the example, the producer component runs and generates messages that
 
 . Switch back to the first command-line window.
 +
-You should now see that the consumer component displays the same country names generated by the producer, and in the same order, as shown in the example.
+You now see that the consumer component displays the same country names generated by the producer, and in the same order, as shown in the following example:
 +
 .Example output from the consumer component
 [source]
 ----
-$ node consumer.js
 Ghana
 Réunion
 Guatemala
@@ -334,7 +328,7 @@ Haiti
 +
 The output from both components confirms that they successfully connected to the Kafka instance. The components are using the Kafka topic that you created to produce and consume messages.
 +
-NOTE: You can also use the {product-long-kafka} web console to browse messages in the Kafka topic. For more information, see {base-url}{message-browsing-url-kafka}[_Browsing messages in the {product-long-kafka} web console_^].
+NOTE: You can also use the {product-long-kafka} web console to browse messages in the Kafka topic. For more information, see {base-url}{message-browsing-url-kafka}[Browsing messages in the {product-long-kafka} web console^].
 
 . In your IDE, in the `producer-backend` directory of the repository that you cloned, open the `producer.js` file.
 +