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 <https://pulsar.apache.org/docs/2.11.x/admin-api-topics/#get-stats> ) It's really hard to understand both from the document and PIP itself the problems. The "who/what/" is too vague.
2. What exactly do we plan to change? I couldn't understand what we plan to change, *practically*. I would expect something like: * The table of content would look like this... and mention the TOC and explain briefly each section. * Each endpoint would be documented as such: and supply a template/example for one. On Wed, Mar 15, 2023 at 9:30 AM Yu <li...@apache.org> wrote: > 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 <wander4...@gmail.com> wrote: > > > 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 40 pages look like a survey to be > > referred to, instead of the proposal itself. > > > > Best, > > tison. > > > > > > Dave Fisher <w...@apache.org> 于2023年3月15日周三 10:38写道： > > > > > 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 > July > > > 2022. > > > > > > The second document is the real PIP. Please share the detail in a > > friendly > > > way in a PIP issue. > > > > > > This is an important effort and I’m sure that the community will want > to > > > easily suggest improvements. Doing this in an issue or even an email > > thread > > > would really help. > > > > > > Best, > > > Dave > > > > > > Sent from my iPhone > > > > > > > On Mar 14, 2023, at 6:38 PM, Yu <li...@apache.org> wrote: > > > > > > > > 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 the community. > > > > > > > >> On Wed, Mar 15, 2023 at 12:08 AM Asaf Mesika <asaf.mes...@gmail.com > > > > > wrote: > > > >> > > > >> 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 <li...@apache.org> wrote: > > > >>> > > > >>> 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 > > > >>> information architecture for Pulsar API content in *PIP-256: > Building > > > >> Great > > > >>> Developer Experience with API Content* [2], which explains: > > > >>> > > > >>> - What is API content? > > > >>> - Why does API content matter? > > > >>> - How to design API content? > > > >>> - Design thinking > > > >>> - Design process > > > >>> - Deliverables, implement timeline and progress > > > >>> ... > > > >>> > > > >>> Feel free to share your thoughts on this proposal, TIA! > > > >>> > > > >>> [1] > > > >>> > > > >>> > > > >> > > > > > > https://docs.google.com/document/d/1H-wEEfut18M18dle6a4-2EWCnLOqyJ81RVYxkPkTXhk/edit > > > >>> [2] > > > >>> > > > >>> > > > >> > > > > > > https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.xgnk69nwtqi > > > >>> > > > >>> Yu > > > >>> > > > >> > > > > > > > > >
