Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

Hi Asaf, Thanks for your explanations! Now I understand your point. I've summarized the doc issues, solutions, corresponding changes, task status, and more here [1]. Also, add the link to the issue. PTAL, TIA! [1] https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/ed

Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

I'll rephrase what I mean. Why I finish reading https://github.com/apache/pulsar/issues/19755, I should be able to answer the following questions, *without* resorting to reading external links (i.e. Google Doc): 1. What exactly is problematic with current API docs? List concisely a bullet point l

Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

Hi Asaf, thanks for your questions! Please see my response below. > 1. What are the exact problems we have? As stated in the Motivation, there were several issues in previous docs (2.11.x and earlier versions). The biggest one was " many contents are missing"

Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

I read the PIP but I can't understand the following: 1. What are the exact problems we have? I can say for example that a concrete issue is that the parameters for the rest API endpoints are not documented at all. (see getStats )

Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

Hi Dave and tison, thanks for your feedback! I've added the required info and explanations to the PIP issue [1] concisely. Feel free to take a look and leave your suggestions. TIA! [1] https://github.com/apache/pulsar/issues/19755 Yu On Wed, Mar 15, 2023 at 11:11 AM tison wrote: > Hi Yu, > >

Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

Hi Yu, Thanks for starting this thread! Perhaps you can reorganize the content in PIP template form so that we known the background and what is proposed at first. I read the doc and the changes proposed are at the last six pages (Changing the Admin API docs information architecture). The previous

Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

Hi Yu, Your first document is really website analytics which should be shared with the community which might have different conclusions. It would be helpful in understanding motivation. I feel it needs to be in an issue as markdown where it is easy to review. I’ll note that it is dated from Jul

Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

Hi Asaf, thanks for your reminder! The corresponding issue was filed at https://github.com/apache/pulsar/issues/19755 previously. Since it's a large initiative containing many content and complex formats, I've made it in Google Docs first and will relocate them to the issue once it's accepted by

Re: [Discuss] PIP-256: Building Great Developer Experience with API Content

Side note: PIP should be in markdown in a GitHub issue for prosperity. External links lose permissions over time, come and go. On Mon, Mar 13, 2023 at 6:00 PM Yu wrote: > Hi community, > > Based on the [2022 Report] Pulsar Website Content Analysis (GA) [1], the > Pulsar API doc is one of the t

[Discuss] PIP-256: Building Great Developer Experience with API Content

Hi community, Based on the [2022 Report] Pulsar Website Content Analysis (GA) [1], the Pulsar API doc is one of the top-viewed content. However, Pulsar API was not systematically and logically explained previously. To address this issue, I've created a content strategy and designed the informatio