[refactor][doc] Refactor the information architecture of Schema topics by momo-jun · Pull Request #18242 · apache/pulsar

momo-jun · 2022-10-28T09:19:15Z

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

Curate a new Overview topic to introduce WHAT/WHY/HOW about Schema.
Curate a new Get Started topic to introduce how to construct a schema.
Improve the IA inside the Understand Schema and Schema evolution and compatibility topics. -- Will evaluate whether it makes more sense to merge Schema evolution and compatibility into Understand Schema with more reviews.
Relocate content in Manage Schema into Admin Interfaces - Schemas (new) and Understand Schema" topics.
Move examples and references from Client Libraries - Java/C++ to a single source inside Get started.
Remove duplicate or redundant information.

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

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

RobertIndie · 2022-11-03T03:32:18Z

+        .create();
+```
+
+The following schema formats are currently available for Java:


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.

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:)

RobertIndie · 2022-11-03T03:42:43Z

+  client.subscribe("topic-avro", "sub-2", consumerConf, consumer)
+  ```
+
+### ProtobufNative schema using C++


Do we also need to talk about ProtobufNative schema using Java?

Agree. Will leave it to the next round of content review/revise because this PR focuses more on the information architecture changes.

RobertIndie · 2022-11-03T03:55:43Z

-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).


Better to briefly explain SEPARATED here.

Agree. Will leave it to the next round of content review/revise because this PR focuses more on the information architecture changes.

momo-jun · 2022-11-03T08:43:48Z

@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 :)

momo-jun · 2022-11-04T02:57:33Z

@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.

congbobo184 · 2022-11-04T03:51:02Z

-##### Type
+#### `struct` schema

 `struct` schema supports `AvroBaseStructSchema` and `ProtobufNativeSchema`.


AvroSchema JsonSchema etc. is struct schema, later we should add these

I've added the comment in the Google doc as part of the content review.

congbobo184 · 2022-11-04T03:54:50Z

+* 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


whether move to understand schema, the user may not understand how it works here, and may not care about it in the Overview

Makes sense. I think it also helps users understand what schema is. This move can be considered and improved in the content review.

congbobo184 · 2022-11-04T03:59:45Z

+### 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.


Can we delete it? doesn't seem to say anything

Indeed. Can be considered and improved in the content review.

congbobo184 · 2022-11-04T04:13:09Z

-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


can we move this to Understand Schema? It feels awkward to put it here, the user must have enough context to understand it

Yes, will be done in the next move. Leaving it in this PR just to track the changes made to it.

re-org the schema chapter

0e21eda

github-actions Bot added the doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. label Oct 28, 2022

momo-jun added 4 commits October 28, 2022 21:59

update sidebar

e114bdb

add more info to What and Why

399980a

relocate code snippets from java/cpp clients to Schema chapter

d3bdf2e

Merge branch 'master' into schema

59b69c1

momo-jun marked this pull request as ready for review October 31, 2022 08:27

momo-jun requested review from RobertIndie and congbobo184 October 31, 2022 08:34

momo-jun self-assigned this Oct 31, 2022

momo-jun added 2 commits October 31, 2022 16:48

preview style fix

4ab981f

preview fixes

6ec26b3

momo-jun mentioned this pull request Nov 1, 2022

[Doc] Refactor the information architecture and content of Schema #18151

Closed

3 tasks

overview updates

d5147df

RobertIndie reviewed Nov 3, 2022

View reviewed changes

fix review comments

6b07633

Update schema-get-started.md

18db6c7

congbobo184 reviewed Nov 4, 2022

View reviewed changes

Update schema-understand.md

e862ab7

congbobo184 approved these changes Nov 4, 2022

View reviewed changes

Technoboy- added this to the 2.12.0 milestone Nov 5, 2022

Technoboy- merged commit ce67c98 into apache:master Nov 5, 2022

momo-jun mentioned this pull request Nov 11, 2022

[refactor][doc] Improve schema docs #18434

Merged

4 tasks

momo-jun mentioned this pull request Dec 8, 2022

PIP-228: Refactor Information Architecture of Pulsar Client Documentation #18822

Open

sijie mentioned this pull request Dec 9, 2022

ISSUE-18822: PIP-228: Refactor Information Architecture of Pulsar Client Documentation streamnative/pulsar-archived#5227

Open

Uh oh!

Conversation

momo-jun commented Oct 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Modifications

Documentation

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

momo-jun commented Nov 3, 2022

Uh oh!

momo-jun commented Nov 4, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

momo-jun commented Oct 28, 2022 •

edited

Loading