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 > > > > > >>> > > > > > >> > > > > > > > > > > > > > > > > > > > >
