DOC-4449 Astra Streaming audit and remove unnecessary duplications of Serverless content #121

aimurphy · 2024-10-16T17:57:31Z

DOC-4449 is for the settings UI overhaul for Astra Portal. While scoping this ticket, I found Astra Portal documentation in the Astra Streaming docs. Most of this content is specific to Streaming, which is not impacted by the new settings UI. However, there was some content that was related to organization settings (tokens, SSO, roles, permissions).

Rather than try to maintain this content in two places, I elected to remove (or minimize, insofar as possible) the dependencies on core Astra DB content within the Streaming docs. Because Streaming is an extension of an Astra DB org, it makes sense for the Streaming docs to reference the main Astra DB docs for org management and DB information. Additionally, it makes sense to assume the user has some exposure to the rest of Astra DB, being that Streaming is embedded in the Portal. Once we have a proper reuse system in place, we can consider adding content back in, if it is useful.

Furthermore, the Streaming docs have been in need of a general audit for some time. I guess I was feeling bold after my Classic docs audits and decided to take a stab at the Streaming docs. 😓 Admittedly, I used rather broad strokes here, and there is much more to be done. My general goals included auditing the following:

Syntax for tables, tabs, admonitions, source blocks
Headings in sentence-case with no gerunds
Attribute usage (astra_db, product, astra_cli, company)
Units of measure (kB, MB, GB, TB)
Uniform headings for related links (See also, Next steps)
Use terms like {company} and you instead of we, us, etc.

In the course of the audit tasks, removing the dependencies on Astra DB documentation, and learning about Streaming in general, I took to the time to make more significant revisions to some pages. Sometimes this was in pursuit of a well-structured page, and other times it was to address possible sources of confusion, such as inconsistent or incomplete information.

Full page reviews

The following pages were edited enough to warrant a review of the entire page:

FAQs (2 topics [1] [2]): I revised the majority of the questions to provide clarity or improve the page structure. Removed questions were either duplicates or moved to another page. Eventually I want to combine these into one topic. For now, they remain separate.
astream-org-permissions: Renamed to Manage roles and permissions. It now includes only content that is directly relevant to Streaming with multiple links to the general Astra DB RBAC page (in the Serverless docs).
Subscriptions (5 pages - Overview, exclusive, shared, failover, key shared + a partial): General rewrite.
apis/index.adoc: General rewrite
astra-cli: Copy the generic description from the Serverless docs. Show only one code example, strictly relevant to Streaming.
astream-functions: Rewrote and reorganized the entire page
Clients (7 pages - Overview, Java, Python, C#, Golang, Node.js, Spring + a partial): General rewrite.
configure-pulsar-env: General rewrite
produce-consume-pulsar-client: General rewrite
using-curl: Repurpose into a proper "How to form HTTP requests" page.
getting-started/index.adoc: Repurpose into a Portal-focused quickstart. The programmatic instructions had some inconsistencies with other topics, and they were missing essential setup. The Portal steps are simple and quick. This can be revisited in the future from a programmatic standpoint.
astream-limits: Economize and rewrite
astream-pricing: Add information about subscription plans, cluster types, additional billed charges, and the relationship between an Astra DB subscription plan and a Streaming subscription plan.
astream-token-gen: Remove redundant information about creating Astra DB application tokens. Economize and improve the explanations of the two token types and their uses.
monitoring/integration: General rewrite
monitoring/new-relic: General rewrite

Navigation

The Streaming docs have 5 separate nav files (and I would like to combine these into a single nav eventually). I made the following changes to the navigation:

Remove gerunds in section titles, such as Developing (now Development) and Producing and consuming messages (now Produce and consume messages).
Remove the IO connectors section that had only one external link within. The IO connectors link is now under Development.
Remove the Guides and examples section. The Manage permissions and Pulsar subscriptions topics are now under Operations > Administration and Development > Produce and consume messages, respectively.
Move the using-curl topic from Development to API references, where it is most relevant.
Under Development, the gpt-schema-translator topic is no longer the first topic, and the astra-cli topic is closer to the end of the section. If a user follows the nav, it is more appropriate to encounter these topics later in the flow.
Under Operations, the geo-replication topic is no longer the first topic. It is now immediately after the regions topic.
Under Operations, there is now an Administration section with the tokens, private links, and roles/permissions topics.

Lesser changes

The following pages received insubstantial changes or changes that aren't visible in the published output. I provided some preview links, but most of these pages need further revisions. A substantial review isn't necessary for these pages. If you wish to review the changes, please examine the diff on Files changed.

antora.yml: Changed product_name to product to align with other doc sets.
ROOT:index.adoc: Removed the small limits and related links sections from the end of the page because this page is meant to be the Streaming landing page.
astream-cdc: This page is a duplicate of pages in the Serverless and Classic docs. I need to figure out what to do about this duplication.
Generic audit stuff:
- astream-kafka.adoc
- astream-rabbit.adoc
- produce-consume-astra-portal
- astream-regions
- astream-release-notes
- astream-scrape-metrics
- monitoring/namespace-dashboard
- monitoring/overview-dashboard
- monitoring/topic-dashboard
- operations/partials/georeplication-monitoring
- operations/partials/code-examples-text
- stream-audit-logs
- private-connectivity
gtp-schema-translator: I attempted to clean up and rewrite this topic, but it needs more work and testing. Entire chunks of instructions were (and are) missing.
astream-georeplication: Partially rewrote the introduction and first section, but the page needs more work.
monitoring/index.adoc: Mostly syntax/audit changes, with the exception of the Aggregate Astra Streaming metrics section, which I rewrote due to poor IA.
monitoring/metrics: I don't think this page is necessary. It could be removed in a future revision.
API operations: This page needs a lot more work. For now, I did some general clean up:
- Combined 2 prerequisites sections into one.
- Removed inappropriately used tabs.
- Use collapsibles for results.
- Replaced insubstantial results with a description of the expected result (namely when there is no response).
- Level 2 headings now indicate the correct parent API that the operations belong to (either the Streaming DevOps API or the Pulsar Admin API).
- I did not clean up the code due to the amount of content and that I think this page should be approached differently. It's not providing any more value than the Swagger references, currently.

Deletions

RAGStack module & contents: Deleted. See explanation in the following Redirects section.
astream-custom-roles.adoc: Deleted due to redundancy. Redirected to astream-org-permissionstopic. Seeastream-org-permissions` in the preceding Full page reviews section.
ROOT/partials/georeplication-monitoring: Duplicate of a partial in another module.
operations/partials/subscritpion-prereq: Duplicate of a partial in another module.