Anonymitaet commented on issue #19912:
URL: https://github.com/apache/pulsar/issues/19912#issuecomment-1489677523
Hi @asafm
Thanks for your awesome proposal. The real-world examples are great
additions to the docs!
## Issues
While there are some issues in the current proposal:
1. The learning paths of 3 roles are blurred.
If we put all the topics (as below) into a single [Get
started](https://pulsar.apache.org/docs/next/getting-started-home/), all roles
will read them all by sequence, which means a clear learning path is not
designed in real.
```
Introduction to Pulsar using CLI
Introduction to Pulsar using sample applications
Introduction to Pulsar using operational scenarios
```
2. Headings are lengthy.
[Main
headings](https://github.com/apache/pulsar/issues/19912#issuecomment-1488195941)
are too long.
For example, for `Introduction to Pulsar using CLI`, actually users care
little about the method (whether it's CLI or API) to produce msg.
What they want is to try and get a successful result (with whatever the
method) in a minimal time.
So "method" can be hidden in headings to save space since headings
should show the "keypoint" and be "concise" as much as possible.
## Solutions
To resolve the issues above, I would suggest that:
1. Create 3 guides for 3 roles respectively.
2. Show 3 guides on the doc landing page to provide specific paths for
different roles. Users do not need to wander on the Pulsar site or Google
around to find suitable docs.
3. Make 3 guides as subpages of https://pulsar.apache.org/docs since:
- Each role has a "dedicated" container to show all relevant docs.
- Resue docs from https://pulsar.apache.org/docs is possible.
### Reasons of proposed solutions
(1) It highlights the roles and gives them what they need clearly. No
missing or duplicates (MVP).
(2) It makes short headings possible.
Besides, for the common docs (e.g., concepts, references) which should be
reused, we can link them richly in the 3 guides.
<img width="1960" alt="image"
src="https://user-images.githubusercontent.com/50226895/228725100-c1746c7c-e95a-4c1e-ad1b-8aaf9b17f9e8.png";>
## Examples
- [Starburst docs](https://docs.starburst.io/)
Each role has its independent guide (sub-page).
<img width="1145" alt="image"
src="https://user-images.githubusercontent.com/50226895/228725174-5b25633e-40f0-4ff4-b8f8-3686e63e3989.png";>
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
![https://user-images.githubusercontent.com/50226895/228725100-c1746c7c-e95a-4c1e-ad1b-8aaf9b17f9e8.png"](https://user-images.githubusercontent.com/50226895/228725100-c1746c7c-e95a-4c1e-ad1b-8aaf9b17f9e8.png"){kind=link}
![https://user-images.githubusercontent.com/50226895/228725174-5b25633e-40f0-4ff4-b8f8-3686e63e3989.png"](https://user-images.githubusercontent.com/50226895/228725174-5b25633e-40f0-4ff4-b8f8-3686e63e3989.png"){kind=link}