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". Previously, Pulsar admin API content had nothing but the "reference" [1]. It shows only brief descriptions, commands, and flags and does not contain context (Who/What/Why/When/Where/How), guides, tutorials, examples, demos, etc. > The "who/what/" is too vague. "Who" means who is the primary target audience of Pulsar API content. I've analyzed various personas and described them in "Pulsar API users" [2]. "What" means the deliverables that we need to create for different users at different stages, which are designed based on the following factors: - User knowledge level (dev levels) - User journey stage (discover and research → evaluate → get started → implement and troubleshoot → celebrate → maintain) - User needs (what are their goals?) - Learning habits (where do they look for info) - Learning path (how do they learn?) ... I've explained them in "Pulsar user journey stages and API content" [3]. ==================================== > 2. What exactly do we plan to change? Actually, we (+@hangc0276) have made significant doc changes based on this idea. Click this [4] to check out the new docs. ==================================== [1] "Reference" refers to - REST API reference: https://pulsar.apache.org/admin-rest-api/?version=2.11.0 - Java admin API reference: https://pulsar.apache.org/api/admin/2.11.x/ - pulsar-admin reference: https://pulsar.apache.org/reference/#/2.11.x/pulsar-admin → This should not be on the "Pulsar admin API" guide but it was. [2] https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=kix.2ttjjn5z1ovo [3] https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.xgnk69nwtqi [4] https://lists.apache.org/thread/d7w276y70230onczqkodhskg38kjpl8d On Wed, Mar 15, 2023 at 9:43 PM Asaf Mesika <asaf.mes...@gmail.com> wrote: > 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 > > > > >>> > > > > >> > > > > > > > > > > > > > >
