= DataStax Streaming Documentation Site :toc: macro :toc-title: Readme Topics: :toclevels: 1
As a line of business at DataStax, Streaming represents multiple products. Each product may or may not have versioning. Each may or may not be open sourced. Antora is a great fit for such a dynamic environment and the Streaming docs team utilizes its features extensively.
To continue into Streaming Documentation it is assumed that you have a solid understand of Antora playbooks and how Antora compiles a site. https://docs.antora.org/antora/latest/how-antora-works/[Start here] if you don't.
toc::[]
== Products that make up Streaming documentation
[cols="2,3,1,2",options="header"] |=== | Display Name | Project Repo | Public | Docs URL Path*
| DataStax Streaming Documentation Site | https://github.com/datastaxdocs/datastax-streaming-docs-site[datastaxdocs/datastax-streaming-docs-site] | Y | /streaming
| DataStax Astra Streaming | https://github.com/datastax/astra-streaming-docs[datastax/astra-streaming-docs] | Y | /streaming/astra-streaming/
| DataStax Luna Streaming | https://github.com/datastax/pulsar-docs[datastax/pulsar-docs] | Y | /streaming/luna-streaming
| Starlight for Kafka | https://github.com/datastax/starlight-for-kafka-docs[datastax/starlight-for-kafka-docs] | Y | /streaming/starlight-for-kafka
| Starlight for RabbitMQ | https://github.com/datastax/starlight-for-rabbitmq-docs[datastax/starlight-for-rabbitmq-docs] | Y | /streaming/starlight-for-rabbitmq
| Starlight for JMS | https://github.com/datastax/starlight-for-jms-docs[datastax/starlight-for-jms-docs] | Y | /streaming/starlight-for-jms
| DataStax Streaming Leaning Site | https://github.com/datastax/streaming-learning-docs[datastax/streaming-learning-docs] | Y | /learning |===
*assuming a URL prefix of https://docs.datastax.com/en
=== DataStax Streaming Documentation Site
This is the "parent" site to the entire line of business. There are only 1-2 pages in the entire site, with no formal left navigation. The pages are meant to be high-level "directional" pages, helping someone understand what products have documentation, their purpose in the world, and a link to that product's index page.
=== DataStax Astra Streaming
Documentation site for the Astra Streaming product.
=== DataStax Luna Streaming
Documentation site for the Luna Streaming product.
=== Starlight for Kafka
Documentation site for the Kafka API in the Starlight suite.
=== Starlight for RabbitMQ
Documentation site for the RabbitMQ API in the Starlight suite.
=== Starlight for JMS
Documentation site for the JMS API in the Starlight suite.
=== DataStax Streaming Leaning Site
A learning site covering topics that span multiple Streaming products, or talk about Apache Pulsar concepts.
== Getting started
It is assumed that you have a good understanding of how Antora works. You'll need that knowledge to understand why things have been arranged in a certain way. The following steps will get your local environment ready to edit and compile the different DataStax Streaming documentation areas.
. If built correctly you should have a new _build folder that holds the compiled Streaming documentation site.
. Open the parent datastax-streaming-site folder in your editor of choice.
It's not recommended to open each site's folder individually (i.e. code ./).
== Goals of documentation
=== Imperative configurations
The purpose if using Antora is to combine each product's documentation into one complete site. To do so means that configurations should be clearly defined with little interpretation. To achieve this the team takes an imperative approach. The playbooks are the source of truth. The command to build the site is simplistic by design. It is not recommended to override playbook settings with command line options.
=== Treat each product as domain of knowledge
Each product is considered a domain of knowledge about the functions it can run. The documentation follows that same philosophy. Global attributes should be thoughtful and -actually- be needed throughout the different sites. Otherwise, local attributes (located in that site's antora.yml) should always be the default.
=== No loose ends
Search engines don't like it when they index a page and then it is removed. Uses like it even less. When a page makes it to production, that path is forever taken. Either by an actual page as the canonical path or as a redirect to a canonical page. Make all possible efforts to never redirect to generic pages. Users get frustrated when they think they are being taken to a page talking about -this this feature- but are actually given a page talking about -a bunch of generic stuff this does-.
== Managing redirects
The DataStax documentation site is running on an https://httpd.apache.org/[Apache HTTP server]. It has a https://httpd.apache.org/docs/current/rewrite/remapping.html[certain spec] for creating redirects when a page is moved or removed. Antora has provisions to write a redirect file upon building the site that follows this spec. https://docs.antora.org/antora/latest/playbook/urls-redirect-facility/#httpd[Read more here].
The Streaming site uses https://docs.antora.org/antora/latest/page/page-aliases/[Antora's page-aliases] explicitly to represent a redirection of some kind. In turn a properly formatted .htaccess file is created and given to the server un startup. Read more about htaccess files https://httpd.apache.org/docs/current/howto/htaccess.html[here].