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/edit?pli=1#bookmark=id.6soebl1lbvj0 On Sun, Mar 19, 2023 at 9:43 PM Asaf Mesika <asaf.mes...@gmail.com> wrote: > 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 list of problems. For example: > - REST API docs are missing parameters and their description. > - There are no examples per endpoint > - There aren't any tutorials for those who like to learn by doing compared > with by reading. > - There is no DevOps path and Dev path: a TOC page for developers and a TOC > page for DevOps (TOC = Table of Content) > ... > > 2. What are the exact changes we plan to make to improve the API docs? > A list of specific changes, usually in the form of a table of contents and > for each section listing a small description of what it will contain. > > Right now when you read the PIP, you can't answer those questions above. > > > > On Thu, Mar 16, 2023 at 2:14 PM Yu <li...@apache.org> wrote: > > > 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 > > > > > > >>> > > > > > > >> > > > > > > > > > > > > > > > > > > > > > > > > > > >
