You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2022/09/01 16:58:03 UTC
[GitHub] [pulsar] tisonkun opened a new issue, #17409: [Doc] Simplify the get started page for local cluster
tisonkun opened a new issue, #17409:
URL: https://github.com/apache/pulsar/issues/17409
### Search before asking
- [X] I searched in the [issues](https://github.com/apache/pulsar/issues) and found nothing similar.
### What issue do you find in Pulsar docs?
The current [Get Started page for local cluster](https://pulsar.apache.org/docs/next/getting-started-standalone) 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?
- [X] I'm willing to submit a PR!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] DaveDuggins commented on issue #17409: [Doc] Simplify the get started page for local cluster
Posted by GitBox <gi...@apache.org>.
DaveDuggins commented on issue #17409:
URL: https://github.com/apache/pulsar/issues/17409#issuecomment-1235654356
@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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] tisonkun commented on issue #17409: [Doc] Simplify the get started page for local cluster
Posted by GitBox <gi...@apache.org>.
tisonkun commented on issue #17409:
URL: https://github.com/apache/pulsar/issues/17409#issuecomment-1236839244
@Anonymitaet Patch at https://github.com/apache/pulsar/pull/17475. For your suggestions:
> Next steps (It provides hints and related useful resources). For example,
Good point! Addressed at https://github.com/apache/pulsar/pull/17475/commits/e1bd5cece9c13ef2f0d84fe938b394a5077116e2.
> Binary release info - If so, suggest keeping this part
Accepted. Addressed at https://github.com/apache/pulsar/pull/17475/commits/e758f05411fc75f84a396eebe2c461e1e706cc4c.
> 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on issue #17409: [Doc] Simplify the get started page for local cluster
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on issue #17409:
URL: https://github.com/apache/pulsar/issues/17409#issuecomment-1234964144
@tisonkun thanks for raising this up! I'm on your side to make it more concise and task-focused.
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](https://pulsar.apache.org/case-studies).
> - To know how Pulsar solves infrastructure challenges and how it compares to similar projects, see [Pulsar Concepts and Architecture](https://pulsar.apache.org/docs/next/concepts-overview).
> - To use Pulsar in real-world applications, see [Use Pulsar Client](https://pulsar.apache.org/docs/client-libraries).
☘️☘️☘️
### 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](https://pulsar.apache.org/docs/next/getting-started-standalone#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](https://chaos-mesh.org/docs/quick-start/#faq).
- Method 2: collect all common issues and solutions in another place (eg. Create an independent `Troubleshooting` guide, create posts on [Discussions](https://github.com/apache/pulsar/discussions), or elsewhere) and attach its link to the `Get Started` guide
☘️☘️☘️
Thank you!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet closed issue #17409: [Doc] Simplify the get started page for local cluster
Posted by GitBox <gi...@apache.org>.
Anonymitaet closed issue #17409: [Doc] Simplify the get started page for local cluster
URL: https://github.com/apache/pulsar/issues/17409
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] tisonkun commented on issue #17409: [Doc] Simplify the get started page for local cluster
Posted by GitBox <gi...@apache.org>.
tisonkun commented on issue #17409:
URL: https://github.com/apache/pulsar/issues/17409#issuecomment-1235668484
@Anonymitaet Thanks for your information! 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).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org