jc-1721-a connectors gs cleanup (#616)

* jc-1721-a connectors gs cleanup

* jc-1731-a peer review

* jc-1731-a peer review 2

* jc-1731-a peer review 3

Author: MelissaFlinn

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

@@ -107,9 +107,9 @@ Welcome to the quick start for {product-long-connectors}.
 
 In this quick start, you learn how to create a source connector and sink connector and send data to and from {product-kafka}.
 
-A *source* connector allows you to send data from an external system to {product-kafka}. 
+A _source_ connector allows you to send data from an external system to {product-kafka}. 
 
-A *sink* connector allows you to send data from {product-kafka} to an external system.
+A _sink_ connector allows you to send data from {product-kafka} to an external system.
 ====
 endif::[]
 
@@ -129,55 +129,55 @@ Before you use {product-connectors}, you must complete the following prerequisit
 
 For Service Preview, you have two choices:
 
-* *The hosted evaluation environment*
+* *The hosted preview environment*
 
 ** The {connectors} instances are hosted on a multitenant {osd-name-short} cluster that is owned by Red Hat.
 ** You can create four {connectors} instances at a time.
-** The evaluation environment applies 48-hour expiration windows, as described in https://access.redhat.com/documentation/en-us/openshift_connectors/1/guide/8190dc9e-249c-4207-bd69-096e5dd5bc64[Red Hat {openshift} {connectors} Service Preview evaluation guidelines^].
+** The preview environment applies 48-hour expiration windows, as described in https://access.redhat.com/documentation/en-us/openshift_connectors/1/guide/8190dc9e-249c-4207-bd69-096e5dd5bc64[Red Hat {openshift} {connectors} Service Preview guidelines^].
 
 * *Your own trial environment*
 
 ** You have access to your own {osd-name-short} trial environment.
 ** You can create an unlimited number of {connectors} instances.
 ** Your {osd-name-short} trial cluster expires after 60 days.
-** A cluster administrator must install the {product-connectors} add-on as described in https://access.redhat.com/documentation/en-us/openshift_connectors/1/guide/15a79de0-8827-4bf1-b445-8e3b3eef7b01[Adding the Red Hat {openshift} {connectors} add-on to your {osd-name-short} trial cluster^].
+** A cluster administrator has installed the {product-connectors} add-on as described in https://access.redhat.com/documentation/en-us/openshift_connectors/1/guide/15a79de0-8827-4bf1-b445-8e3b3eef7b01[Adding the Red Hat {openshift} {connectors} add-on to your {osd-name-short} trial cluster^].
 
 *Configuring {product-long-kafka} for use with {product-connectors}*
 
 ifndef::qs[]
-Complete the steps in _{base-url}{getting-started-url-kafka}[Getting started with {product-long-kafka}^]_ to set up the following components:
+Complete the steps in {base-url}{getting-started-url-kafka}[Getting started with {product-long-kafka}^] to set up the following components:
 endif::[]
 
 ifdef::qs[]
 Complete the steps in the link:https://console.redhat.com/application-services/learning-resources?quickstart=getting-started[Getting started with {product-long-kafka}] quick start to set up the following components:
 endif::[]
 
-* A *Kafka instance* that you can use for {product-connectors}.
-* A *Kafka topic* to store messages sent by data sources and make the messages available to data sinks.
-* A *service account* that allows you to connect and authenticate your {connectors} instances with your Kafka instance.
-* *Access rules* for the service account that define how your {connectors} instances can access and use the topics in your Kafka instance.
+* A _Kafka instance_ that you can use for {product-connectors}.
+* A _Kafka topic_ to store messages sent by data sources and make the messages available to data sinks.
+* A _service account_ that allows you to connect and authenticate your {connectors} instances with your Kafka instance.
+* _Access rules_ for the service account that define how your {connectors} instances can access and use the topics in your Kafka instance.
 
 ifdef::qs[]
 .Procedure
 Make sure that you have set up the prerequisite components.
 
 .Verification
-* Is the Kafka instance listed in the Kafka instances table and is the Kafka instance in the *Ready* state?
-* Is your service account created in the *Service Accounts* page?
+* Is the Kafka instance listed on the *Kafka Instances* page and is the Kafka instance in the *Ready* state?
+* Is your service account created on the *Service Accounts* page?
 * Did you save your service account credentials to a secure location?
-* Are the permissions for your service account listed in the *Access* page of the Kafka instance?
-* Is the Kafka topic that you created for {connectors} listed in the topics table of the Kafka instance?
+* Are the permissions for your service account listed on the *Access* page of the Kafka instance?
+* Is the Kafka topic that you created for {connectors} listed on the *Topics* page of the Kafka instance?
 * If you plan to use a 60-day {osd-name-short} trial cluster to deploy your {product-connectors} instances, has a cluster administrator added the {product-connectors} add-on to your trial cluster?
 
 endif::[]
 
 ifndef::qs[]
 .Verification
-* Verify that the Kafka instance is listed in the Kafka instances table and that the state of the Kafka instance is shown as *Ready*.
-* Verify that your service account was successfully created in the *Service Accounts* page.
+* Verify that the Kafka instance is listed on the *Kafka Instances* page and that the state of the Kafka instance is shown as *Ready*.
+* Verify that your service account was successfully created on the *Service Accounts* page.
 * Verify that you saved your service account credentials to a secure location.
-* Verify that the permissions for your service account are listed in the *Access* page of the Kafka instance.
-* Verify that the Kafka topic that you created for {product-connectors} is listed in the Kafka instance's topics table.
+* Verify that the permissions for your service account are listed on the *Access* page of the Kafka instance.
+* Verify that the Kafka topic that you created for {product-connectors} is listed on the *Topics* page of the Kafka instance.
 * If you plan to use a 60-day {osd-name-short} trial cluster to deploy your {product-connectors} instances, verify that a cluster administrator added the {product-connectors} add-on to your trial cluster.
 
 endif::[]
@@ -187,66 +187,62 @@ endif::[]
 == Creating a {connectors} instance for a data source
 
 [role="_abstract"]
-A *source* connector consumes events from an external data source and produces Kafka messages.
+A _source_ connector consumes events from an external data source and produces Kafka messages.
 
-For this example, you create an instance of the *Data Generator* source connector.
+You configure your {connectors} instance to listen for events from the data source and produce a Kafka message for each event. Your {connectors} instance sends the messages at regular intervals to the Kafka topic that you created for {connectors}.
 
-You configure your connector to listen for events from the data source and produce a Kafka message for each event.
-
-The connector sends the messages at regular intervals to the Kafka topic that you created for your {connectors} instances.
+For this example, you create an instance of the Data Generator source connector. The Data Generator is provided for development and testing purposes. You specify the text for a message and how often to send the message.
 
 ifndef::qs[]
 .Prerequisites
 * You're logged in to the {product-long-connectors} web console at {service-url-connectors}[^].
 endif::[]
 
 .Procedure
-. In the {product-long-connectors} web console, select *{connectors}* and then click *Create {connectors} instance*.
+. In the {product-long-connectors} web console, click *Create a {connectors} instance*.
 . Select the connector that you want to use for connecting to a data source.
 +
 You can browse through the catalog of available connectors. You can also search for a particular connector by name, and filter for sink or source connectors.
 +
-For example, to find the *Data Generator* source connector, type *data* in the search box. The list filters to show only the *Data Generator Connector* card.
+For example, to find the Data Generator source connector, type `data` in the search box. The list is filtered to show only the *Data Generator source* card.
 +
 Click the card to select the connector, and then click *Next*.
 
-. For *Kafka instance*, click the card for the {product-kafka} instance that you configured for {connectors}, and then click *Next*.
+. On the *Kafka Instance* page, click the card for the {product-kafka} instance that you configured for {connectors}, and then click *Next*.
 
 . On the *Namespace* page, the namespace that you select depends on your {osd-name-short} environment. The namespace is the deployment space that hosts your {connectors} instances.
 +
 If you're using a trial cluster in your own {osd-name-short} environment, select the card for the namespace that was created when a system administrator added the {connectors} service to your trial cluster, as described in https://access.redhat.com/documentation/en-us/openshift_connectors/1/guide/15a79de0-8827-4bf1-b445-8e3b3eef7b01[Adding the Red Hat {openshift} {connectors} add-on to your {osd-name-short} trial cluster^].
 +
-If you're using the evaluation {osd-name-short} environment, click *Register eval namespace* to provision a namespace for hosting the {connectors} instances that you create.
+If you're using the hosted preview environment, click *Create preview namespace* to provision a namespace for hosting the {connectors} instances that you create.
 
 . Click *Next*.
 
-. Configure the core configuration for your {connectors} instance:
-.. Type a name for your {connectors} instance.
-.. Type the *Client ID* and *Client Secret* of the service account that you created for {connectors} and then click *Next*.
-. Provide connector-specific configuration. For the *Data Generator*, provide the following information:
-.. *Data shape Format*: Accept the default, `application/octet-stream`.
-.. *Topic Names*: Type the name of the topic that you created for {connectors}. For example, type *test-topic*.
+. Specify the core configuration for your {connectors} instance:
+.. Type a name for your {connectors} instance. For example, type `hello world generator`.
+.. In the *Client ID* and *Client Secret* fields, type the credentials for the service account that you created for {connectors} and then click *Next*.
+. Provide connector-specific configuration. For the Data Generator, provide the following information:
+.. *Topic Name*: Type the name of the Kafka topic that you created for {connectors}. For example, type `test-topic`.
 .. *Content Type*: Accept the default, `text/plain`.
-.. *Message*: Type the content of the message that you want the {connectors} instance to send to the Kafka topic. For example, type `Hello World!`.
-.. *Period*: Specify the interval (in milliseconds) at which you want the {connectors} instance to send messages to the Kafka topic. For example, specify `10000`, to send a message every 10 seconds.
+.. *Message*: Type the content of the message that you want the {connectors} instance to send to the Kafka topic. For example, type `Hello World!!`.
+.. *Period*: Specify the interval (in milliseconds) at which you want the {connectors} instance to send messages to the Kafka topic. For example, to send a message every 10 seconds, specify `10000`.
+.. *Data Shape Produces Format*: Accept the default, `application/octet-stream`.
 
-. Optionally, configure the error handling policy for your {connectors} instance.
-+
-The options are:
-+
-* *stop*: (the default) The {connectors} instance shuts down when it encounters an error.
-* *log*: The {connectors} instance sends errors to its log.
-* *dead letter queue*: The {connectors} instance sends messages that it cannot handle to a dead letter topic that you define for the {connectors} Kafka instance.
+. Click *Next*.
+
+. Select one of the following error handling policy for your {connectors} instance:
 +
-For example, accept the default *stop* option.
+* *Stop*: If a message fails to send, the {connectors} instance stops running and changes its status to *Failed* state. You can view the error message. 
+* *Ignore*: If a message fails to send, the {connectors} instance ignores the error and continues to run. No error message is logged.
+* *Dead letter queue*: If a message fails to send, the {connectors} instance sends error details to the Kafka topic that you specify.
 
 . Click *Next*.
 
 . Review the summary of the configuration properties and then click *Create {connectors} instance*.
 +
-Your {connectors} instance is listed in the table of {connectors}. After a couple of seconds, the status of your {connectors} instance changes to the *Ready* state and it starts producing messages and sending them to its associated Kafka topic.
+Your {connectors} instance is listed on the *{connectors} Instances* page. After a couple of seconds, the status of your {connectors} instance changes to the *Ready* state and it starts producing messages and sending them to its associated Kafka topic.
 +
-From the {connectors} table, you can stop, start, and delete your {connectors} instance, as well as edit its configuration, by clicking the options icon (three vertical dots).
+From the *{connectors} Instances* page, you can stop, start, duplicate, and delete your {connectors} instance, as well as edit its configuration, by clicking the options icon (three vertical dots).
 
 .Verification
 ifdef::qs[]
@@ -259,60 +255,63 @@ endif::[]
 .. In the {product-long-rhoas} web console, select *Streams for Apache Kafka* > *Kafka Instances*.
 .. Click the Kafka instance that you created for connectors.
 .. Click the *Topics* tab and then click the topic that you specified for your source {connectors} instance.
-.. Click the *Messages* tab to see a list of `Hello World!` messages.
+.. Click the *Messages* tab to see a list of `Hello World!!` messages.
 
 
 [id="proc-creating-sink-connector_{context}"]
 == Creating a {connectors} instance for a data sink
 
 [role="_abstract"]
-A *sink* connector consumes messages from a Kafka topic and sends them to an external system.
+A _sink_ connector consumes messages from a Kafka topic and sends them to an external system.
 
-For this example, you use the *HTTP Sink* connector which consumes the Kafka messages (produced by the source {connectors} instance) and sends the messages to an HTTP endpoint.
+For this example, you use the *HTTP Sink* connector which consumes the Kafka messages (produced by your Data Generator source {connectors} instance) and sends the messages to an HTTP endpoint.
 
-ifndef::qs[]
 .Prerequisites
+
+ifndef::qs[]
 * You're logged in to the {product-long-connectors} web console at {service-url-connectors}[^].
-* You created the source {connectors} instance as described in _Creating a {connectors} instance for a data source_.
-* For the data sink example, open the free https://webhook.site[webhook.site^] in a browser window. The `webhook.site` page provides a unique URL that you copy for use as an HTTP data sink.
 endif::[]
+* You created a Data Generator source {connectors} instance.
+* For the data sink example, open the free https://webhook.site[webhook.site^] in a browser window. The `webhook.site` page provides a unique URL that you copy for use as an HTTP data sink.
+
 
 .Procedure
 
 . In the {product-long-connectors} web console, click *Create {connectors} instance*.
 
 . Select the sink connector that you want to use:
-.. For example, type *http* in the search field. The list of {connectors} filters to show the *HTTP Sink* connector.
-.. Click the *HTTP Sink connector* card and then click *Next*.
+.. For example, type `http` in the search field. The list of {connectors} is filtered to show the *HTTP sink* connector.
+.. Click the *HTTP sink* card and then click *Next*.
 
-. Select the {product-kafka} instance for the connector to work with.
+. On the *Kafka Instance* page, select the {product-kafka} instance for the connector to work with.
 +
 For example, select *test* and then click *Next*.
 
 . On the *Namespace* page, the namespace that you select depends on your {osd-name-short} environment. The namespace is the deployment space that hosts your {connectors} instances.
 +
 If you're using a trial cluster on your own {osd-name-short} environment, select the card for the namespace that was created when you added the {connectors} service to your trial cluster.
 +
-If you're using the evaluation {osd-name-short} environment, click the *eval namespace* that you created when you created the source connector.
+If you're using the hosted preview environment, click the *preview namespace* that you provisioned when you created the source connector.
 
 . Click *Next*.
 
 . Provide the core configuration for your connector:
-.. Type a unique name for the connector.
-.. Type the *Client ID* and *Client Secret* of the service account that you created for {connectors} and then click *Next*.
+.. Type a unique name for the connector. For example, type `hello world receiver`.
+.. In the *Client ID* and *Client Secret* fields, type the credentials for the service account that you created for {connectors} and then click *Next*.
 
-. Provide the connector-specific configuration for your {connectors} instance. For the *HTTP sink connector*, provide the following information:
-
-.. *Data shape Format*: Accept the default, `application/octet-stream`.
+. Provide the connector-specific configuration for your HTTP sink {connectors} instance:
+.. *Topic Names*: Type the name of the topic that you used for the source {connectors} instance. For example, type `test-topic`.
 .. *Method*: Accept the default, `POST`.
 .. *URL*: Type your unique URL from the link:https://webhook.site[webhook.site^].
-.. *Topic Names*: Type the name of the topic that you used for the source {connectors} instance. For example, type *test-topic*.
+.. *Data Shape Consumes Format*: Accept the default, `application/octet-stream`.
+
+. Click *Next*.
 
-. Optionally, configure the error handling policy for your {connectors} instance. For example, select *log* and then click *Next*.
+. Select an error handling policy for your {connectors} instance. For example, select *Stop* and then click *Next*.
 
 . Review the summary of the configuration properties and then click *Create {connectors} instance*.
 +
-Your {connectors} instance is listed in the table of {connectors}.
+Your {connectors} instance is added to the *{connectors} Instances* page.
 +
 After a couple of seconds, the status of your {connectors} instance changes to the *Ready* state. It consumes messages from the associated Kafka topic and sends them to the data sink (for this example, the data sink is the HTTP URL that you provided).