asafm commented on issue #19912: URL: https://github.com/apache/pulsar/issues/19912#issuecomment-1489989713
Thanks for the detailed reply! Regarding the suggestion of moving the getting started for each role into it's own sub-section of a bigger guide (developer, operator): I was thinking about it. My big plan was indeed to have 2 additional guides, a Developer Guide and an Operator Guide. If we zoom in, for example on the developer role, the two (getting started , developer) serve a completely different purpose: * The getting started guide is aimed at developers who hate learning by reading. They like to learn by doing. This mean, starting with a ready made example, tweak to their needs. Basically, tutorial style. They want "just" the minimum amount of knowledge to get it done. Hence this guide is designed exactly like that: examples, which includes the minimum amount of knowledge you need to understand them. * The developer guide on the other hand, is aimed at people who are the exact opposite: They like to read the book, sometimes start to finish before they even write a single line of code. Those people, like to understand first, do later. Hence the guide it self will really be designed like a book, explaining all the details. So, when I think about it, in my opinion it's confusing to have in the same guide, two contradictory sections: We'll have a Getting Started section which is basically a tutorial. So the people that like to read first do later, will be confused - "so we're suppose to get started here, but what's going on? I see code here, no no no. I want to understand first. what's going here?". On the other hand, the people like to do first, read later, will not search inside a Developer Guide the getting started. For them, a Developer's Guide is big scary book, filled with way too many details. If you ask them, all they want is tutorials, from the getting started ones, to more complicated ones. So I imagined having a section in the docs named Tutorials, that contains exactly that, grouped by role (developer, operator). So from that perspective I prefer to have: Getting Started Developer Guide Operator Guide Regarding second suggestion of having sub-pages of docs. You mean each guide will have their own "doc site"? I think it depends if Docosaurus allow more than 2 depths in the left side bar. I personally like all docs to be in a single location - I don't like to jump around between sites. That's my personal preference. Regarding >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. Why do you think that if the side bar has: Getting Started - Introduction to Pulsar using CLI - Introduction to Pulsar using sample applications - Introduction to Pulsar using operational scenarios then people will read them one after another? If I'm a developer, I would naturally ignore operational scenarios, right? Why do I care? I do agree the titles are too lengthy. Maybe we can try: * Getting Started * Pulsar using CLI "Launch Pulsar locally, and "feel" it using the command line tools" * Pulsar using sample applications "Learn the 2 most popular use cases by running ready-made sample applications, and learning just what you need to get it working" * Pulsar using operational scenarios "Run a demo environment including apps, on k8s, and run through common operational scenarios" -- 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]
