DOC-4949 - Attribute refinement for Astra Streaming (#128)

* attributes pt 1

* attributes pt 2

* attributes pt 3

* syntax

* slight changes/copying for accuracy

Author: aimurphy

antora.yml

@@ -12,17 +12,26 @@ nav:
 
 asciidoc:
   attributes:
+    company: 'DataStax'
+    astra-db: 'Astra DB'
     product: 'Astra Streaming'
+    product-short: 'Astra'
+    astra-cli: 'Astra CLI'
+    astra-ui: 'Astra Portal'
+    astra-url: 'https://astra.datastax.com'
+    astra-ui-link: '{astra-url}[{astra-ui}^]'
+    devops-api: 'DevOps API'
+    cass: 'Apache Cassandra'
+    cass-reg: 'Apache Cassandra(R)'
+    cass-short: 'Cassandra'
     pulsar: 'Apache Pulsar'
     pulsar-short: 'Pulsar'
     pulsar-reg: 'Apache Pulsar(TM)'
     pulsar-version: '2.10' #DO NOT INCLUDE PATCH VERSION <MAJOR>.<MINOR>.<PATCH>
     pulsar-version-patch: '2.10.1'
-    kafka_for_astra: 'Starlight for Kafka'
-    starlight_rabbitmq: 'Starlight for RabbitMQ'
+    kafka-for-astra: 'Starlight for Kafka'
+    starlight-rabbitmq: 'Starlight for RabbitMQ'
     gpt-schema-translator: 'GPT schema translator'
-    url-astra: 'https://astra.datastax.com'
-    link-astra-portal: '{url-astra}[{astra_ui}^]'
     astra-streaming-examples-repo: 'https://raw.githubusercontent.com/datastax/astra-streaming-examples/master'
 
     # LEGACY ATTRIBUTES - CONSIDER REMOVING

modules/ROOT/pages/astream-faq.adoc

@@ -28,17 +28,17 @@ The pricing model also makes {product} accessible to mid market and small/medium
 
 And finally {product} offers a user-friendly interface and free tier to satisfy the needs of individual developers and technologists who want to learn more about {pulsar} and data streaming in general.
 
-== What is CDC for {astra_db}?
+== What is CDC for {astra-db}?
 
-Change Data Capture (CDC) for {astra_db} uses a {pulsar-short} IO source connector that processes changes from the Cassandra Change Agent through a {pulsar-short} topic.
+Change Data Capture (CDC) for {astra-db} uses a {pulsar-short} IO source connector that processes changes from the {cass-short} Change Agent through a {pulsar-short} topic.
 For more information, see xref:developing:astream-cdc.adoc[].
 
 == What are tenants, namespaces, topics, and sinks?
 
 *Tenants* are an isolated administrative unit for which an authorization scheme can be set and a set of clusters can be defined.
 Each tenant can have multiple *namespaces*, a logical container for creating and managing a hierarchy of topics.
 A *topic* is a named channel for transmitting messages from producers to consumers.
-A *sink* feeds data from {product} to an external system, such as {cassandra} or Elasticsearch.
+A *sink* feeds data from {product} to an external system, such as {cass-reg} or Elasticsearch.
 
 == See also
 

modules/ROOT/pages/astream-org-permissions.adoc

@@ -1,18 +1,19 @@
-= Manage roles and permissions
+= Manage {product} roles and permissions
+:navtitle: Manage roles and permissions
 :page-tag: astra-streaming,security,secure,pulsar
 
-You manage role-based access control (RBAC) for {product} through your {astra_db} organization.
-For information about {astra_db} RBAC, including default roles, custom roles, permissions, and user management, see xref:astra-db-serverless:administration:manage-database-access.adoc[].
+You manage role-based access control (RBAC) for {product} through your {astra-db} organization.
+For information about {astra-db} RBAC, including default roles, custom roles, permissions, and user management, see xref:astra-db-serverless:administration:manage-database-access.adoc[].
 
 == {product} permissions
 
 Permissions specific to {product} include the following:
 
-* *Manage Streaming* (`org-stream-manage`): View, add, edit, or remove Astra Streaming configurations.
+* *Manage Streaming* (`org-stream-manage`): View, add, edit, or remove {product} configurations.
 
 === Default roles for {product}
 
-There are no default {astra_db} roles specifically scoped to {product}.
+There are no default {astra-db} roles specifically scoped to {product}.
 However, the following default roles have the *Manage Streaming* permission:
 
 * *Organization Administrator*
@@ -26,8 +27,8 @@ For information about permissions assigned to default roles, see xref:astra-db-s
 
 If you xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[create custom roles] for {product}, those roles must have the following permissions, at minimum:
 
-* *Manage Streaming* (`org-stream-manage`): View and manage {product} in the {astra_ui}.
-* *View DB* (`org-db-view`): View the {astra_ui} in general.
+* *Manage Streaming* (`org-stream-manage`): View and manage {product} in the {astra-ui}.
+* *View DB* (`org-db-view`): View the {astra-ui} in general.
 
 Additional permissions might be required, depending on the tasks the role needs to perform.
 
@@ -36,22 +37,22 @@ Additional permissions might be required, depending on the tasks the role needs
 To control access to specific streaming tenants, you can set granular xref:astra-db-serverless:administration:manage-database-access.adoc#role-scopes[resource scopes] on custom roles.
 ====
 
-== Authentication and authorization in {pulsar-reg} and {astra_db}
+== Authentication and authorization in {pulsar-reg} and {astra-db}
 
 {pulsar-short} has the concept of https://pulsar.apache.org/docs/security-authorization/[clients with role tokens].
 In {pulsar-short}, authentication is the process of verifying a provided token (JWT), and authorization is the process of determining if the role claimed in that token is allowed to complete the requested action.
 
 {product} uses the {company} version of {pulsar} (xref:luna-streaming::index.adoc[Luna Streaming]).
 The https://github.com/datastax/pulsar[Luna project] is an open fork of the {pulsar-short} project that maintains feature parity with OSS {pulsar-short}. {product}, as a managed service, abstracts some features/options of {pulsar-short} to ensure continuous, reliable service.
 
-On a shared cluster, your {astra_db} organization has one or more tenants on a shared {pulsar-short} cluster.
-Each of your tenants is secured by {pulsar-short} authentication and authorization models, as well as your {astra_db} organization's authentication and authorization ({astra_db} RBAC).
+On a shared cluster, your {astra-db} organization has one or more tenants on a shared {pulsar-short} cluster.
+Each of your tenants is secured by {pulsar-short} authentication and authorization models, as well as your {astra-db} organization's authentication and authorization ({astra-db} RBAC).
 
 {product} shared clusters are created and administered by {product} administrators.
 Each tenant is assigned a custom role and permissions limited to that tenant only.
 All tokens created within a tenant are assigned roles similar to the assigning tenant.
 
-For programmatic access, you use {astra_db} application tokens or {pulsar-short} JWT, depending on the operation you need to perform.
+For programmatic access, you use {astra-db} application tokens or {pulsar-short} JWT, depending on the operation you need to perform.
 For more information, see xref:operations:astream-token-gen.adoc[].
 
 == See also

modules/ROOT/pages/index.adoc

@@ -3,14 +3,14 @@
 :page-tag: astra-streaming,planner,admin,dev,pulsar
 
 {product} is a cloud native data streaming and event stream processing
-service tightly integrated into the {astra_ui} and powered by {pulsar-reg}.
+service tightly integrated into the {astra-ui} and powered by {pulsar-reg}.
 Using {product}, customers can quickly create {pulsar-short} instances,
 manage their clusters, scale across cloud regions, and manage {pulsar-short} resources
 such as topics, connectors, functions and subscriptions.
 
-{product} takes advantage of the core capabilities built into {astra_db} such
+{product} takes advantage of the core capabilities built into {astra-db} such
 as SSO, IAM and billing.
-Existing {astra_db} customers can augment their existing database capabilities
+Existing {astra-db} customers can augment their existing database capabilities
 with pub/sub and streaming to address a wider range of use cases right away.
 
 With {product}, customers now have powerful capabilities to help drive key
@@ -33,6 +33,6 @@ their legacy messaging technologies keep up will find {product} to be a
 frictionless path to modernization.
 
 *Faster Access to Data*:: No one has patience for slow loading web pages or mobile apps.
-By combining {product} with {astra_db}, customers can create read-optimized
-views of data that can be quickly read from {astra_db} and ensure that data is
+By combining {product} with {astra-db}, customers can create read-optimized
+views of data that can be quickly read from {astra-db} and ensure that data is
 always up to date by leveraging the event stream processing capabilities of {product}.

modules/apis/pages/api-operations.adoc

@@ -1,19 +1,19 @@
 = API operations
 
 //TODO: Needs more work and clean up of all source blocks.
-This {product} workbook is a comprehensive guide that provides detailed examples and  practices for managing the {product} platform using the DevOps APIs.
+This {product} workbook is a comprehensive guide that provides detailed examples and practices for managing the {product} platform using the {devops-api}s.
 It provides details on the most commonly used APIs for managing {product} and {pulsar-reg} instances.
 These details include required parameters and the expected output from the API.
 The workbook is designed to fill the gap between detailed API reference docs and HowTo guides.
-The result is to help customers in operating and managing {product} and provide guidance on how to use DevOps API to automate many common tasks.
+The result is to help customers in operating and managing {product} and provide guidance on how to use {devops-api}s to automate many common tasks.
 
 The workbook covers a wide range of topics, including provisioning of resources, monitoring, and troubleshooting. It provides instructions for various operations, such as creating a new tenant, namespace, topics, geo-replication, and access tokens, to setting up monitoring and alerting, and troubleshooting common issues.
 
-Overall, this {product} Workbook is a valuable resource for customers who want to leverage the benefits of {product} and manage their streaming environment effectively with DevOps APIs. By following the best practices and guidelines outlined in the workbook, customers can ensure that their streaming applications are secure, performant, and reliable.
+Overall, this {product} Workbook is a valuable resource for customers who want to leverage the benefits of {product} and manage their streaming environment effectively with {devops-api}s. By following the best practices and guidelines outlined in the workbook, customers can ensure that their streaming applications are secure, performant, and reliable.
 
 == Prerequisites
 
-* An active {astra_db} account with access to {product}
+* An active {product-short} account with access to {product}
 * Credentials and values required to xref:developing:using-curl.adoc[form HTTP requests]
 
 === Set environment variables
@@ -42,9 +42,9 @@ The examples in this guide use environment variables for these values.
 Additionally, some examples in this guide use `python3 -mjson.tool` to format the JSON response.
 This is optional; it is not required to execute API requests.
 
-== {product} DevOps API tenant operations
+== {product} {devops-api} tenant operations
 
-The following examples demonstrate how to use the {product} DevOps API to manage {product} resources.
+The following examples demonstrate how to use the {product} {devops-api} to manage {product} resources.
 
 === Get tenant information
 
@@ -842,7 +842,7 @@ curl -sS --fail --location --request POST "$WEB_SERVICE_URL/admin/v2/persistent/
 
 No response indicates success.
 
-== {product} DevOps API geo-replication operations
+== {product} {devops-api} geo-replication operations
 
 === Get status of geo-replication
 
@@ -1159,13 +1159,13 @@ curl --fail --location --request POST "$WEB_SERVICE_URL/admin/v3/functions/$TENA
 
 No response indicates success.
 
-== {product} DevOps API JWT operations
+== {product} {devops-api} JWT operations
 
 === List existing token IDs
 
 Get a list of Token IDs for your Cluster.
 With the TokenID, you can then lookup and obtain the {pulsar-short} JWT string.
-The TokenIDs are also listed in the {astra_ui} for that Tenant and Cluster.
+The TokenIDs are also listed in the {astra-ui} for that Tenant and Cluster.
 
 Required parameters "CLUSTER" is obtained from the "List Tenants with Details" API command.
 
@@ -1210,7 +1210,7 @@ eyJhbGciOiJSUzI1NiIsI . . .
 === Create a JWT
 
 Create a new {pulsar-short} JWT.
-The new JWT will also be visible in the {astra_ui} for that Tenant and Cluster.
+The new JWT will also be visible in the {astra-ui} for that Tenant and Cluster.
 
 Required parameters "CLUSTER" is  obtained from the "List Tenants with Details" API command.
 

modules/apis/pages/index.adoc

@@ -4,11 +4,11 @@
 
 You use two APIs to manage {pulsar-reg} tenants and their resources.
 
-== {product} DevOps API
+== {product} {devops-api}
 
-Use the xref:astra-streaming:apis:attachment$devops.html[{product} DevOps API] to manage higher-level objects associated with your account, such as the change data capture (CDC) settings, {pulsar-short} tenants, geo-replications, {pulsar-short} stats, and {pulsar-short} tokens.
+Use the xref:astra-streaming:apis:attachment$devops.html[{product} {devops-api}] to manage higher-level {product} objects associated with your {astra-db} organization, such as the change data capture (CDC) settings, {pulsar-short} tenants, geo-replications, {pulsar-short} stats, and {pulsar-short} tokens.
 
-This API uses an {astra_db} application token for authentication.
+This API uses an {astra-db} application token for authentication.
 
 == {product} {pulsar-short} Admin API
 

modules/developing/pages/astra-cli.adoc

@@ -1,15 +1,15 @@
-= {astra_cli} overview
-:navtitle: {astra_cli}
-:description: {astra_cli} provides a one-stop shop for managing your Astra resources through scripts or commands in your local terminal.
+= {astra-cli} overview
+:navtitle: {astra-cli}
+:description: {astra-cli} provides a one-stop shop for managing your Astra resources through scripts or commands in your local terminal.
 
-The xref:astra-cli:ROOT:index.adoc[{astra_db} Command-Line Interface ({astra_cli})] is a set of commands you can use to create and manage {astra_db} and {product} resources:
+The xref:astra-cli:ROOT:index.adoc[{astra-db} Command-Line Interface ({astra-cli})] is a set of commands you can use to create and manage {astra-db} and {product} resources:
 
-* Creation and management of {astra_db} databases, {astra_stream} tenants, and their associated artifacts.
+* Creation and management of {astra-db} databases, {astra_stream} tenants, and their associated artifacts.
 * Querying and data loading.
 * Organization and user management.
 * Security and token configuration.
 
-{astra_cli} commands are available for {astra_db} and {astra_stream}.
+{astra-cli} commands are available for {astra-db} and {astra_stream}.
 They're designed to get you working quickly, with an emphasis on automation.
 
 For example, the following command creates an {pulsar-reg} tenant:
@@ -21,8 +21,8 @@ astra streaming create **TENANT_NAME** \
 --plan **PLAN_TYPE** --namespace **TENANT_INITIAL_NAMESPACE_NAME**
 ----
 
-You can use {astra_cli} instead of or in addition to the {astra_ui} and {astra_db} APIs.
+You can use {astra-cli} instead of or in addition to the {astra-ui} and {astra-db} APIs.
 
 For more information, see the following:
 
-* https://www.datastax.com/blog/introducing-cassandra-astra-cli[Accelerate your Cassandra development and automation with the {astra_cli}]
+* https://www.datastax.com/blog/introducing-cassandra-astra-cli[Accelerate your {cass-short} development and automation with the {astra-cli}]

modules/developing/pages/astream-cdc.adoc

@@ -1,14 +1,14 @@
 = Create a Change Data Capture (CDC) connector
-:description: CDC for {astra_db} automatically captures changes in real time, de-duplicates the changes, and streams the clean set of changed data
+:description: CDC for {astra-db} automatically captures changes in real time, de-duplicates the changes, and streams the clean set of changed data
 
 [IMPORTANT]
 ====
-Enabling CDC for {astra_db} databases incurs billed charges based on your {product} usage.
+Enabling CDC for {astra-db} databases incurs billed charges based on your {product} usage.
 See https://www.datastax.com/pricing/astra-streaming[{product} pricing] and https://www.datastax.com/products/datastax-astra/cdc-for-astra-db[CDC metering rates].
 ====
 
-CDC for {astra_db} automatically captures changes in real time, de-duplicates the changes, and streams the clean set of changed data into {product} where it can be processed by client applications or sent to downstream systems.
+CDC for {astra-db} automatically captures changes in real time, de-duplicates the changes, and streams the clean set of changed data into {product} where it can be processed by client applications or sent to downstream systems.
 
 {product} processes data changes via an {pulsar-reg} topic. By design, the Change Data Capture (CDC) component is simple, with a 1:1 correspondence between the table and a single {pulsar-short} topic.
 
-For instructions and more information about CDC for {astra_db}, see xref:astra-db-serverless:databases:change-data-capture.adoc[].
+For instructions and more information about CDC for {astra-db}, see xref:astra-db-serverless:databases:change-data-capture.adoc[].