[refactor][doc] Refactor the information architecture of Schema topics #18242
Conversation
github-actions
bot
added
the
doc
| .create(); | ||
| ``` | ||
|
|
||
| The following schema formats are currently available for Java: |
There was a problem hiding this comment.
This section seems to be introducing the Avro schema, but why are other schemas also introduced here?
If we want to indicate that all these schemas are based on Avro protocol, then I think it's better to use Avro based schema ... as the title. Otherwise, it will make uses confused because there is an AvroSchema based on Avro protocol.
There was a problem hiding this comment.
Agree. I added a new heading to introduce these examples as a quick twist. Most content changes in this PR are a copy&paste to implement a quick information architecture change. A thorough content review will be done in the following week through Google docs:)
| client.subscribe("topic-avro", "sub-2", consumerConf, consumer) | ||
| ``` | ||
|
|
||
| ### ProtobufNative schema using C++ |
There was a problem hiding this comment.
Do we also need to talk about ProtobufNative schema using Java?
There was a problem hiding this comment.
Agree. Will leave it to the next round of content review/revise because this PR focuses more on the information architecture changes.
| Pulsar provides the following methods to encode a key/value pair in messages： | ||
| You can choose the encoding type when constructing the key/value schema.： | ||
| * `INLINE` - Key/value pairs are encoded together in the message payload. | ||
| * `SEPARATED` - see [Construct a key/value schema](schema-get-started.md#construct-a-keyvalue-schema). |
There was a problem hiding this comment.
Better to briefly explain SEPARATED here.
There was a problem hiding this comment.
Agree. Will leave it to the next round of content review/revise because this PR focuses more on the information architecture changes.
|
@RobertIndie Thanks for your review and comments. I addressed some of them and will leave the others to the next follow-up PR. Because this PR focuses more on the information architecture changes, and some changes (except the WHAT/WHY in the Overview) are a copy&paste work among topics. A thorough content review will be done in the following week through Google docs to add/change more details and I will invite you as a reviewer :) |
|
@congbobo184 @RobertIndie I've created a Google doc to start the review/revise process on the content and added Zike's comments there. We can collaborate to review/revise in detail there. |
site2/docs/schema-understand.md
Outdated
| This section describes the details of type and usage of the `struct` schema. | ||
|
|
||
| ##### Type | ||
| #### `struct` schema | ||
|
|
||
| `struct` schema supports `AvroBaseStructSchema` and `ProtobufNativeSchema`. |
There was a problem hiding this comment.
AvroSchema JsonSchema etc. is struct schema, later we should add these
There was a problem hiding this comment.
I've added the comment in the Google doc as part of the content review.
| * keeps data compatibility on-track between schema versions. When new schemas are uploaded, the new versions can be read by old consumers. | ||
| * stored in the existing storage layer BookKeeper, no additional system required. | ||
|
|
||
| ## How it works |
There was a problem hiding this comment.
whether move to understand schema, the user may not understand how it works here, and may not care about it in the Overview
There was a problem hiding this comment.
Makes sense. I think it also helps users understand what schema is. This move can be considered and improved in the content review.
| ### How schema evolves? | ||
|
|
||
| For more information, see [Schema compatibility check strategy](#schema-compatibility-check-strategy). | ||
| The answer is [schema compatibility check strategy](#schema-compatibility-check-strategy). It determines how schema compares old schemas with new schemas in topics. |
There was a problem hiding this comment.
Can we delete it? doesn't seem to say anything
There was a problem hiding this comment.
Indeed. Can be considered and improved in the content review.
| @@ -6,29 +6,21 @@ sidebar_label: "Schema evolution and compatibility" | |||
|
|
|||
| Normally, schemas do not stay the same over a long period of time. Instead, they undergo evolutions to satisfy new needs. | |||
|
|
|||
| This chapter examines how Pulsar schema evolves and what Pulsar schema compatibility check strategies are. | |||
| This chapter introduces how Pulsar schema evolves and what compatibility check strategies it adopts. | |||
|
|
|||
| ## Schema evolution | |||
There was a problem hiding this comment.
can we move this to Understand Schema? It feels awkward to put it here, the user must have enough context to understand it
There was a problem hiding this comment.
Yes, will be done in the next move. Leaving it in this PR just to track the changes made to it.
Motivation
Improve the doc set of the Schema chapter to provide Pulsar users with a more accurate, easy-to-read, and comprehensive information experience.
Fixes #18151
Modifications
Overviewtopic to introduce WHAT/WHY/HOW about Schema.Get Startedtopic to introduce how to construct a schema.Understand SchemaandSchema evolution and compatibilitytopics. -- Will evaluate whether it makes more sense to mergeSchema evolution and compatibilityintoUnderstand Schemawith more reviews.Manage SchemaintoAdmin Interfaces - Schemas(new) andUnderstand Schema"topics.Client Libraries - Java/C++to a single source insideGet started.Note that this PR is a quick change to the overall IA of security topics. The detailed content updates and improvements will be continued and reviewed in a follow-up PR.
Documentation
docdoc-requireddoc-not-neededdoc-complete