[Doc] Simplify the get started page for local cluster

[tisonkun]

Search before asking

• I searched in the issues and found nothing similar.

What issue do you find in Pulsar docs?

The current Get Started page for local cluster is too much redundant than it should be. Most users want a short happy path to boot a Pulsar cluster and play with it by producing and consuming messages. Although, the current page begins the "Start Pulsar standalone" at almost 2/3 below the whole page.

1. We don't have to teach users to install JDK on M1. They can Google it, and there're a large portion of users who don't use M1. At least troubleshooting should go at last.
2. We don't have to mention how to install connectors or offloaders, it's unused on the quickstart page. We can mention them on the overview/quickstart page of connectors and offloaders.
3. We don't have to talk in detail about the layout of the binary release directory. It's intuitive and can be read from their name.
4. Currently, if you go through the page, you won't get the message consumed as it said. Because we don't even produce any message yet. Also, Pulsar CLI has some significant arguments to play with basic messaging, like how to consume from Earliest, how to keep consuming messaging instead of consuming only one message, and how to produce multiple messages in one turn. I have a draft to rewrite the section.

What is your suggestion?

I'll make a draft patch to cover all of the topics listed above in a few days.

cc @merlimat @Anonymitaet @momo-jun @lhotari @codelipenghui

Any reference?

No response

Are you willing to submit a PR?

• I'm willing to submit a PR!

[Anonymitaet]

@tisonkun thanks for raising this up!

I'm on your side to make the Get Started guide more concise and task-focused since it's closely related to the download action in user flow (GA).

Here are my two cents:

☘️☘️☘️

General structure

It can be:

• Prerequisites
• Install Pulsar
• Run Pulsar
• Next steps (It provides hints and related useful resources). For example,

• To learn how other users are getting value out of Pulsar, see Pulsar Case Studies.
• To know how Pulsar solves infrastructure challenges and how it compares to similar projects, see Pulsar Concepts and Architecture.
• To use Pulsar in real-world applications, see Use Pulsar Client.

☘️☘️☘️

Binary release info

We don't have to talk in detail about the layout of the binary release directory. It's intuitive and can be read from their name.

Does "layout of the binary release directory" refer to What your package contains?

If so, suggest keeping this part since

1. some directory names do not reflect the contents
2. it provides more context for novices

We can change the way to show this part if it occupies too much space before Run Pulsar.

☘️☘️☘️

Install connectors and offloaders

I'm with you to relocate this part.

They can be moved to the Get Started chapter of Connector and Tiered Storage guides.

☘️☘️☘️

Run Pulsar

Also, Pulsar CLI has some significant arguments to play with basic messaging, like how to consume from Earliest, how to keep consuming messaging instead of consuming only one message, and how to produce multiple messages in one turn.

+1 for adding a few simple examples of different behaviors of consuming/producing msgs.

☘️☘️☘️

FAQ

To locate troubleshooting info (eg. how to install JDK on M1, other solutions for common issues, etc), which way do you prefer?

• Method 1: put them in the FAQ chapter at the end of the Get stated guide, like Chaos Mesh.

• Method 2: collect all common issues and solutions in another place (eg. Create an independent Troubleshooting guide, create posts on Discussions, or elsewhere) and attach its link to the Get Started guide

☘️☘️☘️

Thank you!

[DaveDuggins]

@tisonkun, I was preparing to edit these docs today. Thank you very much for your help! I'll work together with you and Yu to improve the documentation. I'll wait until you submit your draft to take any action.

[tisonkun]

@Anonymitaet Thanks for your suggestions! I'll try to integrate your comment, submit the patch and answer which ones I accepted.

@DaveDuggins Good to know :) Looking forward to co-work on the content.

FYI - the estimate is by the next Monday (20220905).

[tisonkun]

@Anonymitaet Patch at #17475. For your suggestions:

Next steps (It provides hints and related useful resources). For example,

Good point! Addressed at e1bd5ce.

Binary release info - If so, suggest keeping this part

Accepted. Addressed at e758f05.

FAQ

"how to install JDK on M1" is not suitable to document on the Get Started page. Imagine that you don't tell users how to buy a computer. It's far away from Pulsar topics. Users can resolve it with Google, StackOverflow, etc.

For the FAQ topic itself, I think we can adopt both of them according to the concrete situation. Since it's unrelated to this patch, I'd like to skip the decision but prompt when we meet a real issue.

Prerequisites

Actually no prerequisites except a JRE. It's included in the prelude and trivial to any potential users.

More details

Previously, we said Pulsar supports running on Windows. But all scripts are for the bash shell. So actually it's not completely true.

Besides, there're too many OS and arch in the world. We don't have to mention them one by one, but since Pulsar can work on most of the major platforms, let users execute the commands and file any issue if "it doesn't work for me".