You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pulsar.apache.org by Yu <li...@apache.org> on 2023/03/13 16:00:00 UTC
[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
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
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by Yu <li...@apache.org>.
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 <as...@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 <as...@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 <wa...@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 <wa...@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.mesika@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
> > > > > > >>>
> > > > > > >>
> > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by Asaf Mesika <as...@gmail.com>.
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 <as...@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 <wa...@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 <wa...@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.mesika@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
> > > > > >>>
> > > > > >>
> > > > >
> > > > >
> > > >
> > >
> >
>
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by Yu <li...@apache.org>.
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 <as...@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 <wa...@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 <wa...@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.mesika@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
> > > > >>>
> > > > >>
> > > >
> > > >
> > >
> >
>
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by Asaf Mesika <as...@gmail.com>.
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 <wa...@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 <wa...@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.mesika@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
> > > >>>
> > > >>
> > >
> > >
> >
>
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by Yu <li...@apache.org>.
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 <wa...@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 <wa...@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 <as...@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
> > >>>
> > >>
> >
> >
>
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by tison <wa...@gmail.com>.
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 <wa...@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 <as...@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
> >>>
> >>
>
>
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by Dave Fisher <wa...@apache.org>.
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 <as...@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
>>>
>>
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by Yu <li...@apache.org>.
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 <as...@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
> >
>
Re: [Discuss] PIP-256: Building Great Developer Experience with API Content
Posted by Asaf Mesika <as...@gmail.com>.
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
>