[improve][doc] SEO for Concepts and Architecture except Overview and Messaging #674

zuobiao-zhou · 2023-08-11T05:16:23Z

This PR do SEO for Concepts and Architecture.

doc
doc-required
doc-not-needed
doc-complete

zuobiao-zhou · 2023-08-11T05:23:22Z

tisonkun · 2023-08-11T05:45:34Z

docs/reference-terminology.md

@@ -78,18 +67,6 @@ A group of namespaces that have anti-affinity to each other.
 A lightweight Pulsar broker in which all components run in a single Java Virtual Machine (JVM) process. Standalone
 clusters can be run on a single machine and are useful for development purposes.

-### Cluster


Any background why we remove these terms?

As we have included the definitions of certain terms in the Concepts and Architecture chapter, redundant terminology definitions would add to the maintenance complexity. Users can refer to this chapter when seeking the definitions of specific terms.

Perhaps we can place a link at the repeated term's location in "reference-terminology.md" as a substitute for those redundant definitions?

e.g.

Producer

See here.

On the other hand, for instance, when a user searches for "what is Pulsar brokers," we expect the result is https://pulsar.apache.org/docs/next/concepts-architecture-overview instead of https://pulsar.apache.org/docs/next/reference-terminology/. Repetitive definitions would disperse the weight of the expected page.

I don't think it's necessary to keep those items empty and add links in the reference-terminology.md because we want to navigate users to "concept" topics only on purpose.

Thanks for your explanation!

Anonymitaet · 2023-08-14T00:20:37Z

docs/concepts-architecture-overview.md

@@ -56,7 +57,7 @@ In a Pulsar instance:

 ## Configuration store

-The configuration store maintains all the configurations of a Pulsar instance, such as clusters, tenants, namespaces, partitioned topic-related configurations, and so on. A Pulsar instance can have a single local cluster, multiple local clusters, or multiple cross-region clusters. Consequently, the configuration store can share the configurations across multiple clusters under a Pulsar instance. The configuration store can be deployed on a separate ZooKeeper cluster or deployed on an existing ZooKeeper cluster.
+The Configuration store is a ZooKeeper quorum that is used for configuration-specific tasks and it maintains all the configurations of a Pulsar instance, such as clusters, tenants, namespaces, partitioned topic-related configurations, and so on. A Pulsar instance can have a single local cluster, multiple local clusters, or multiple cross-region clusters. Consequently, the configuration store can share the configurations across multiple clusters under a Pulsar instance. The configuration store can be deployed on a separate ZooKeeper cluster or deployed on an existing ZooKeeper cluster.


Suggested change

The Configuration store is a ZooKeeper quorum that is used for configuration-specific tasks and it maintains all the configurations of a Pulsar instance, such as clusters, tenants, namespaces, partitioned topic-related configurations, and so on. A Pulsar instance can have a single local cluster, multiple local clusters, or multiple cross-region clusters. Consequently, the configuration store can share the configurations across multiple clusters under a Pulsar instance. The configuration store can be deployed on a separate ZooKeeper cluster or deployed on an existing ZooKeeper cluster.

The configuration store is a ZooKeeper quorum that is used for configuration-specific tasks and it maintains all the configurations of a Pulsar instance, such as clusters, tenants, namespaces, partitioned topic-related configurations, and so on. A Pulsar instance can have a single local cluster, multiple local clusters, or multiple cross-region clusters. Consequently, the configuration store can share the configurations across multiple clusters under a Pulsar instance. The configuration store can be deployed on a separate ZooKeeper cluster or deployed on an existing ZooKeeper cluster.

Why capitalize "C"?

Anonymitaet · 2023-08-14T00:21:58Z

docs/concepts-architecture-overview.md



 You can see an illustration of how brokers and bookies interact in the diagram below:

-![Brokers and bookies](/assets/broker-bookie.png)
+![Brokers and bookies in Pulsar](/assets/broker-bookie.png)


Suggested change

![Brokers and bookies in Pulsar](/assets/broker-bookie.png)

![Brokers and bookies in a Pulsar cluster](/assets/broker-bookie.png)

Anonymitaet · 2023-08-14T00:23:44Z

docs/concepts-architecture-overview.md

@@ -144,13 +145,13 @@ Some important things to know about the Pulsar proxy:

 ## Service discovery

-[Clients](concepts-clients.md) connecting to Pulsar brokers need to be able to communicate with an entire Pulsar instance using a single URL.
+Service discovery is a mechanism provided by Pulsar that enables connecting [clients](concepts-clients.md) to use just a single URL to interact with an entire Pulsar instance.


Suggested change

Service discovery is a mechanism provided by Pulsar that enables connecting [clients](concepts-clients.md) to use just a single URL to interact with an entire Pulsar instance.

Service discovery is a mechanism that enables connecting [clients](concepts-clients.md) to use just a single URL to interact with an entire Pulsar instance.

Anonymitaet · 2023-08-14T00:24:11Z

docs/concepts-authentication.md

@@ -2,6 +2,7 @@
 id: concepts-authentication
 title: Authentication and Authorization
 sidebar_label: "Authentication and Authorization"
+description: Get a high level understanding of the concept of Authentication and Authorization in Pulsar.


Suggested change

description: Get a high level understanding of the concept of Authentication and Authorization in Pulsar.

description: Get a high-level understanding of authentication and authorization in Pulsar.

Why capitalize "A"?

Anonymitaet · 2023-08-14T00:30:04Z

docs/concepts-clients.md

-2. Once the client library has the broker address, it creates a TCP connection (or reuses an existing connection from the pool) and authenticates it. Within this connection, the client and broker exchange binary commands from a custom protocol. At this point, the client sends a command to create producer/consumer to the broker, which will comply after having validated the authorization policy.
+1. The client attempts to determine the owner of the topic by sending an HTTP lookup request to the broker. 
+
+    The request could reach one of the active brokers which, by looking at the (cached) zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.


Suggested change

The request could reach one of the active brokers which, by looking at the (cached) zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.

The request could reach one of the active brokers which, by looking at the (cached) Zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.

Anonymitaet · 2023-08-14T00:54:58Z

docs/concepts-throttling.md

@@ -64,7 +65,7 @@ The dispatch rate limits configured at multiple levels take effect simultaneousl

 ### Throttling approaches

-The following table outlines multiple approaches to configure the dispatch rate limits at different levels.
+The following table outlines multiple throttling approaches to configure the dispatch rate limits at different levels.


Suggested change

The following table outlines multiple throttling approaches to configure the dispatch rate limits at different levels.

You can use multiple throttling approaches to configure dispatch rate limits at different levels.

Anonymitaet · 2023-08-14T00:56:28Z

docs/concepts-topic-compaction.md

@@ -2,13 +2,14 @@
 id: concepts-topic-compaction
 title: Topic Compaction
 sidebar_label: "Topic Compaction"
+descriptions: Get a comprehensive understanding of the concept, features and functioning of topic compaction in Apache Pulsar.


Suggested change

descriptions: Get a comprehensive understanding of the concept, features and functioning of topic compaction in Apache Pulsar.

descriptions: Get a comprehensive understanding of concepts, features, and workflow of topic compaction in Apache Pulsar.

Anonymitaet · 2023-08-14T00:57:20Z

docs/concepts-topic-compaction.md

-  * Read beginning at the compaction horizon (if the message ID is lower than the compaction horizon)
+2. After that, the broker will create a new [BookKeeper ledger](concepts-architecture-overview.md#ledgers) and make a second iteration through each message on the topic. For each message:
+
+    - if the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger. 


Suggested change

- if the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger.

- If the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger.

Anonymitaet · 2023-08-14T00:57:40Z

docs/concepts-topic-compaction.md

+    - the ID of the BookKeeper ledger
+    - the message ID of the last compacted message (this is known as the **compaction horizon** of the topic). 


Anonymitaet · 2023-08-14T00:58:09Z

docs/tutorials-tenant.md

@@ -5,7 +5,7 @@ sidebar_label: "Set up a tenant"
 ---


-Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each tenant provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks. 
+Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each t[enant](concepts-multi-tenancy.md#tenants) provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks. 


Suggested change

Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each t[enant](concepts-multi-tenancy.md#tenants) provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks.

Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each [tenant](concepts-multi-tenancy.md#tenants) provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks.

Anonymitaet · 2023-08-14T00:58:58Z

Suggest updating the PR title to reflect the actual changes made in this PR.

…o-C&A

zuobiao-zhou · 2023-08-14T02:01:19Z

fixed, PTAL @Anonymitaet

zuobiao-zhou added 2 commits August 11, 2023 13:08

seo for C&A

f361b44

seo for C&A

121347d

github-actions bot added the doc Improvements or additions to documentation label Aug 11, 2023

Merge branch 'main' into seo-C&A

1645487

tisonkun reviewed Aug 11, 2023

View reviewed changes

Anonymitaet reviewed Aug 14, 2023

View reviewed changes

zuobiao-zhou changed the title ~~seo for C&A~~ SEO for Concepts and Architecture except Overview and Messaging Aug 14, 2023

zuobiao-zhou added 3 commits August 14, 2023 09:48

fix

e94656f

Merge branch 'seo-C&A' of github.com:zuobiao-zhou/pulsar-site into se…

604770e

…o-C&A

fix

a805f49

zuobiao-zhou changed the title ~~SEO for Concepts and Architecture except Overview and Messaging~~ [improve][doc] SEO for Concepts and Architecture except Overview and Messaging Aug 14, 2023

zuobiao-zhou added 2 commits August 14, 2023 15:17

fix

b8a244f

Merge branch 'main' into seo-C&A

1b3dbf5

Anonymitaet added this to the 3.2.0 milestone Aug 16, 2023

Anonymitaet approved these changes Aug 16, 2023

View reviewed changes

Anonymitaet merged commit 97efc11 into apache:main Aug 16, 2023
2 checks passed

zuobiao-zhou deleted the seo-C&A branch August 22, 2023 01:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[improve][doc] SEO for Concepts and Architecture except Overview and Messaging #674

[improve][doc] SEO for Concepts and Architecture except Overview and Messaging #674

zuobiao-zhou commented Aug 11, 2023 •

edited

Loading

zuobiao-zhou commented Aug 11, 2023

tisonkun Aug 11, 2023

zuobiao-zhou Aug 11, 2023

Anonymitaet Aug 14, 2023

tisonkun Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet Aug 14, 2023

Anonymitaet commented Aug 14, 2023

zuobiao-zhou commented Aug 14, 2023

	![Brokers and bookies in Pulsar](/assets/broker-bookie.png)
	![Brokers and bookies in a Pulsar cluster](/assets/broker-bookie.png)

	Service discovery is a mechanism provided by Pulsar that enables connecting [clients](concepts-clients.md) to use just a single URL to interact with an entire Pulsar instance.
	Service discovery is a mechanism that enables connecting [clients](concepts-clients.md) to use just a single URL to interact with an entire Pulsar instance.

	description: Get a high level understanding of the concept of Authentication and Authorization in Pulsar.
	description: Get a high-level understanding of authentication and authorization in Pulsar.

	The request could reach one of the active brokers which, by looking at the (cached) zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.
	The request could reach one of the active brokers which, by looking at the (cached) Zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.

	The following table outlines multiple throttling approaches to configure the dispatch rate limits at different levels.
	You can use multiple throttling approaches to configure dispatch rate limits at different levels.

	descriptions: Get a comprehensive understanding of the concept, features and functioning of topic compaction in Apache Pulsar.
	descriptions: Get a comprehensive understanding of concepts, features, and workflow of topic compaction in Apache Pulsar.

	- if the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger.
	- If the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger.

		- the ID of the BookKeeper ledger
		- the message ID of the last compacted message (this is known as the compaction horizon of the topic).

	Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each t[enant](concepts-multi-tenancy.md#tenants) provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks.
	Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each [tenant](concepts-multi-tenancy.md#tenants) provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks.

[improve][doc] SEO for Concepts and Architecture except Overview and Messaging #674

[improve][doc] SEO for Concepts and Architecture except Overview and Messaging #674

Conversation

zuobiao-zhou commented Aug 11, 2023 • edited Loading

zuobiao-zhou commented Aug 11, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Producer

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Anonymitaet commented Aug 14, 2023

zuobiao-zhou commented Aug 14, 2023

zuobiao-zhou commented Aug 11, 2023 •

edited

Loading