docs: apply style updates to Kafka Getting Started quick start (#599)

* docs: apply style updates to  getting started. reflect some changes to quarkus and nodejs.

* docs: add links to gs in prereqs for quarkus and nodejs

* docs: address peer review feedback

* docs: minor tweak

Author: jbyrne-redhat

docs/kafka/getting-started-kafka/README.adoc

@@ -114,7 +114,7 @@ endif::[]
 == Creating a Kafka instance in {product-kafka}
 
 [role="_abstract"]
-Use the {product-kafka} web console to create and configure a Kafka instance for your applications or services. A Kafka instance in {product-kafka} includes a Kafka cluster, bootstrap server, and the configurations needed for producers and consumers to connect to the instance.
+Use the {product-long-kafka} web console to create and configure a Kafka instance for your applications or services. A Kafka instance in {product-kafka} includes a Kafka cluster, bootstrap server, and the configuration details needed for producers and consumers to connect to the instance.
 
 ifndef::qs[]
 .Prerequisites
@@ -123,11 +123,18 @@ ifndef::qs[]
 endif::[]
 
 .Procedure
-. In the {product-kafka} web console, go to *Streams for Apache Kafka* > *Kafka Instances* and click *Create Kafka instance*.
+. In the {product-kafka} {service-url-kafka}[web console^], select *Kafka Instances* and click *Create Kafka instance*.
++
+The instance creation pane opens, as shown in the figure.
++
+[.screencapture]
+.Kafka instance creation pane
+image::sak-configure-kafka-instance.png[Image of Create Kafka instance pane]
+
 . Enter a unique name for the Kafka instance, such as `my-first-kafka-instance`.
-. From the *Cloud region* drop-down menu, select the relevant option. The selection for availability zones is preconfigured as *Single* for a trial instance and *Multi* for a production instance.
+. In the *Cloud region* list, select the relevant option.
 +
-NOTE: The cloud provider is preconfigured.
+NOTE: The cloud provider is preconfigured to the same value for both trial and production instances. The availability zone value is preconfigured as *Single* for a trial instance and *Multi* for a production instance. 
 +
 ////
 //For post preview, when more options are available.
@@ -144,16 +151,11 @@ For more information about the support scope of Red Hat Technology Preview featu
 
 
 . Click *Create instance* to start the creation process for your Kafka instance.
-
-
++
 --
-[.screencapture]
-.Kafka instance configuration details
-image::sak-configure-kafka-instance.png[Image of instance configuration details in Create Kafka instance window]
-
-The new Kafka instance is listed in the instances table. Typically, you need to wait a few minutes for the instance creation process to finish.
+The new Kafka instance is listed on the *Kafka Instances* page. Typically, you need to wait a few minutes for the instance creation process to finish.
 
-When the instance *Status* is *Ready*, you can start using the Kafka instance. You can use the options icon (three vertical dots) to view instance details, connect to the instance, change the instance owner, or delete the instance.
+When the instance has a status of *Ready*, you can start using the instance. As shown in the following figure, you can click the options icon (three vertical dots) to view instance and connection details, change the instance owner, or delete the instance.
 
 [.screencapture]
 .Kafka instance options menu
@@ -164,41 +166,26 @@ NOTE: Although you can see Kafka instances created by other users in your organi
 
 .Verification
 ifdef::qs[]
-* Is the new Kafka instance listed in the instances table?
-* Is the state of the new Kafka instance shown as *Ready*?
+* Is the new Kafka instance listed on the *Kafka Instances* page?
+* Is the status of the new Kafka instance shown as *Ready*?
 endif::[]
 ifndef::qs[]
-. Verify that the new Kafka instance is listed in the instances table.
-. Verify that the state of the new Kafka instance is shown as *Ready*.
+. Verify that the new Kafka instance is listed on the *Kafka Instances* page.
+. Verify that the status of the new Kafka instance is shown as *Ready*.
 endif::[]
 
-
-////
-// Commenting out the following for now, which belongs in an onboarding tour (Stetson, 4 March 2021)
-
-When you're in the {Product_short} environment, you will see a left menu panel. This panel provides access to all resources related to the service, including the `Quick starts` and `Documentation`.
-
-In the lower left of the screen you'll see a lightbulb icon. This icon gives access to the `Resource Center`. Here you can find the latest information about the service, like product updates, upcoming events, etc.
-
-image::sak-crc-resource-center.png[Image of Resource Center in web console]
-
-The center of the page shows you the list of Kafka instances that are currently running within your organisation. If this is your, or your organisations, first interaction with {Product_short}, this list will be empty.
-
-image::sak-kafka-overview.png[Image of initial empty instances table]
-////
-
 [id="proc-creating-service-account_{context}"]
 == Creating a service account to connect to a Kafka instance in {product-long-kafka}
 
 [role="_abstract"]
-To connect your applications or services to a Kafka instance in {product-long-kafka}, you need to create a service account that's associated with the instance. You also need to save the bootstrap server endpoint for the instance, the generated service account credentials, and the authentication token endpoint to a secure location. You'll use the service account and Kafka instance information later when you configure your application.
+To connect your applications or services to a Kafka instance in {product-long-kafka}, you need to create a service account that's associated with the instance. You then need to save the generated service account credentials, the authentication token endpoint, and the bootstrap server endpoint for the instance to a secure location. You'll use these details when you configure an application to connect to the Kafka instance.
 
 .Prerequisites
-* You've created a Kafka instance and the instance is in the *Ready* state.
+* You have a running Kafka instance in {product-kafka}.
 
 .Procedure
-. In the *Kafka Instances* page of the web console, for the relevant Kafka instance that you want to connect to, select the options icon (three vertical dots) and click *Connection*.
-. In the *Connection* page, copy the *Bootstrap server* endpoint to a secure location. This is the bootstrap server endpoint that you'll need for connecting to this Kafka instance.
+. On the *Kafka Instances* page of the {product-kafka} {service-url-kafka}[web console^], select the options icon (three vertical dots) for your Kafka instance and click *Connection*.
+. On the *Connection* page, copy the *Bootstrap server* endpoint to a secure location. You'll specify this endpoint when configuring a connection to the Kafka instance.
 +
 ifdef::qs[]
 The remainder of this task describes how to create a service account and copy the generated credentials.
@@ -208,18 +195,20 @@ ifndef::qs[]
 The remainder of this section describes how to create a service account and copy the generated credentials.
 If you want to use the credentials of an _existing_ service account, you can skip to the next section.
 endif::[]
+
+. Open the {service-accounts-url}[Service Accounts^] page in the *Application Services* section of the Red Hat Hybrid Cloud Console.
 . Click *Create service account* to set up the account that you'll use to access this Kafka instance.
-. Enter a short description, such as `my-service-account`, and click *Create*.
-. Copy the generated *Client ID* and *Client secret* values to a secure location. These are the credentials that you'll use to connect to this Kafka instance.
+. Enter a short description such as `my-service-account` and click *Create*.
+. Copy the generated *Client ID* and *Client secret* values to a secure location. You'll specify these credentials when configuring a connection to the Kafka instance.
 +
-IMPORTANT: The generated credentials are displayed only one time, so ensure that you've successfully and securely saved the copied credentials before closing the credentials window.
+IMPORTANT: The generated credentials are displayed only once, so ensure that you've successfully and securely saved the copied credentials before closing the credentials window.
 
 . After you save the generated credentials to a secure location, select the confirmation check box in the credentials window and close the window.
-. For the *Authentication method*, copy the SASL/OAUTHBEARER *Token endpoint URL* to a secure location. This is the endpoint that you'll use with your service account credentials to authenticate the connection to this Kafka instance.
+. Under *Authentication method*, copy the SASL/OAUTHBEARER *Token endpoint URL* value to a secure location. This is the endpoint that you'll use with your service account credentials to authenticate the connection to the Kafka instance.
 +
-NOTE: SASL/PLAIN authentication is also available for tools and libraries that don't support SASL/OAUTHBEARER, but SASL/OAUTHBEARER is recommended whenever possible. With SASL/PLAIN authentication, you use only the service account credentials to authenticate the connection to the Kafka instance.
+NOTE: SASL/PLAIN authentication is also available for tools and libraries that don't support SASL/OAUTHBEARER, but SASL/OAUTHBEARER is recommended whenever possible. With SASL/PLAIN authentication, you use only service account credentials to authenticate the connection to the Kafka instance.
 
-. To review, reset, or delete the service account, use the {service-accounts-url}[Service Accounts^] page in the *Application Services* section of the Red Hat Hybrid Cloud Console.
+. (Optional) To review, reset, or delete the service account, use the {service-accounts-url}[Service Accounts^] page.
 
 .Verification
 ifdef::qs[]
@@ -228,24 +217,25 @@ ifdef::qs[]
 endif::[]
 ifndef::qs[]
 . Verify that the bootstrap server, client credentials, and authentication token endpoint are saved to a secure location.
-. Verify that your service account was successfully created in the *Service Accounts* page.
+. Verify that your service account was successfully created on the *Service Accounts* page.
 endif::[]
 
 [id="proc-setting-service-account-permissions_{context}"]
 == Setting permissions for a service account in a Kafka instance in {product-kafka}
 
 [role="_abstract"]
-After you create a service account to connect to a Kafka instance, you must also set the appropriate level of access for that new account in the Access Control List (ACL) of the Kafka instance. {product-kafka} uses ACLs provided by Kafka that enable you to manage how other user accounts and service accounts are permitted to interact with the Kafka resources that you create.
+After you create a service account to connect to a Kafka instance, you must also set the appropriate level of access for that new account in an Access Control List (ACL) for the Kafka instance. {product-long-kafka} uses ACLs provided by Kafka that enable you to manage how other user accounts and service accounts are permitted to interact with the Kafka resources that you create.
 
 .Prerequisites
-* You've created a Kafka instance and the instance is in the *Ready* state.
+* You have a running Kafka instance in {product-kafka}.
 * You've created a service account that you want to allow to access the running Kafka instance.
 
 .Procedure
-. In the *Kafka Instances* page of the web console, click the name of the Kafka instance that you want the service account to access.
+.  In the {product-long-kafka} {service-url-kafka}[web console^], select *Kafka Instances* and then click the name of the Kafka instance that you want the service account to access.
 . Click the *Access* tab to view the current ACL for this instance.
-. Click *Manage access*, use the *Account* drop-down menu to select the service account that you previously created, and click *Next*.
-. Under *Assign Permissions*, use the drop-down menu to select the *Consume from a topic* and the *Produce to a topic* permission options, and set all resource identifiers to `Is` and all identifier values to `*`.
+. To modify the ACL, click *Manage access*.
+. In the *Manage access* dialog box, use the *Account* list to select the service account that you previously created, and click *Next*.
+. Under *Assign Permissions*, use the list to select the *Consume from a topic* and the *Produce to a topic* permission options, and set all resource identifiers to `Is` and all identifier values to `*`.
 +
 --
 These permissions enable applications associated with the service account to create and delete topics in the Kafka instance, to produce and consume messages in any topic in the instance, and to use any consumer group and any producer.
@@ -289,61 +279,65 @@ NOTE: Alternatively, you can click *Add permission* to create individual permiss
 
 .Verification
 ifdef::qs[]
-* Are the new permissions for the service account listed in the *Access* page of the Kafka instance?
+* Are the new permissions for the service account listed on the *Access* page of the Kafka instance?
 endif::[]
 ifndef::qs[]
-* Verify that the new permissions for the service account are listed in the *Access* page of the Kafka instance.
+* Verify that the new permissions for the service account are listed on the *Access* page of the Kafka instance.
 
 [role="_additional-resources"]
 .Additional resources
-* {base-url}{access-mgmt-url-kafka}[_Managing account access in {product-long-kafka}_^]
-* link:https://kafka.apache.org/documentation/#security_authz[Authorization and ACLs^] in Kafka documentation
+* {base-url}{access-mgmt-url-kafka}[Managing account access in {product-long-kafka}^]
+* link:https://kafka.apache.org/documentation/#security_authz[Authorization and ACLs^] in the Apache Kafka documentation
 endif::[]
 
 [id="proc-creating-kafka-topic_{context}"]
 == Creating a Kafka topic in {product-kafka}
 
 [role="_abstract"]
-After you create a Kafka instance, you can create Kafka topics to start producing and consuming messages in your services.
+After you create a Kafka instance, you can create Kafka topics to start producing and consuming messages in your applications and services.
 
 .Prerequisites
-* You've created a Kafka instance and the instance is in the *Ready* state.
+* You have a running Kafka instance in {product-long-kafka}.
 
 .Procedure
-. In the *Kafka Instances* page of the web console, 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. Click *Next* to complete each step and click *Finish* to complete the setup.
+
+. In the {product-long-kafka} {service-url-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-topic.png[Image of wizard to create a topic]
 
+You must specify the following topic properties:
+
 * *Topic name*: Enter a unique topic name, such as `my-first-kafka-topic`.
-* *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.
+* *Partitions*: Set the number of partitions for this topic. This example sets the partitions value to `1`. 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 `A week` 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*: Replicas are copies of partitions in a topic. For this release of {product-kafka}, the replicas are preconfigured. For a standard Kafka instance, 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`. For a trial Kafka instance, the number of replicas and the minimum in-sync replica factor are both set to a fixed value of `1`.  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.
+* *Replicas*: Replicas are copies of partitions in a topic. For this release of {product-kafka}, the replica values are preconfigured. For a standard Kafka instance, 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`. For a trial Kafka instance, the number of replicas and the minimum in-sync replica factor are both set to `1`. 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. You can now start producing and consuming messages to and from this topic using services that you connect to this instance.
+After you complete the topic setup, the new topic is listed on the *Topics* page. You can now start producing and consuming messages to and from this topic using applications that you connect to the Kafka instance.
 
 ifndef::community[]
 NOTE: If you try to create a topic with a number of partitions that would cause the partition limit of the Kafka instance to be exceeded, you see an error message indicating this. For more information about partition limits for Kafka instances, see https://access.redhat.com/articles/5979061[{product-long-kafka} service limits].
 endif::[]
 
 NOTE: If the topic creation is unsuccessful and you see a `400 Bad Request` error message, try to create your topic again later. This situation might occur, for example, if your selected cloud provider has a temporary availability problem that affects your Kafka instance.
-
 --
-. In the topics table, on the right side of the Kafka topic, use the options icon (three vertical dots) to edit or delete the topic as needed.
+
+. (Optional) To edit or delete the topic, click the options icon (three vertical dots) next to the topic name, as shown in the figure.
 +
 [.screencapture]
 .Edit or delete Kafka topic
 image::sak-edit-topic.png[Image of topic options to edit or delete]
 
 .Verification
 ifdef::qs[]
-* Is the new Kafka topic listed in the topics table?
+* Is the new Kafka topic listed on the *Topics* page?
 endif::[]
 ifndef::qs[]
-* Verify that the new Kafka topic is listed in the topics table.
+* Verify that the new Kafka topic is listed on the *Topics* page.
 endif::[]
 
 [role="_additional-resources"]
@@ -366,4 +360,4 @@ You can use either Kafkacat or the Kafka scripts to check that you can connect w
 endif::[]
 
 ifdef::parent-context[:context: {parent-context}]
-ifndef::parent-context[:!context:]
+ifndef::parent-context[:!context:]