PIP-256: Building Great Developer Experience with API Content

### ☘️Context

- This design was created in **Oct 2022** and focuses on **improving docs for Pulsar API**.

- You can check the whole deep research in [[Research] Building Great Developer Experience with API Content](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.bhlu6hsmx1gp), which serves as supplementary material to understand why and how we resolve this issue.

### ☘️Motivation

Issues in the [2.10.x API docs](https://pulsar.apache.org/docs/2.10.x/admin-api-overview/):

- Some docs are inaccurate and make users confused.

For example, the description [You must initialize cluster metadata before starting up any brokers that will belong to the cluster.](https://pulsar.apache.org/docs/next/admin-api-clusters/#initialize-cluster-metadata) is inaccurate and should be updated to `When provisioning a new cluster, you need to initialize the cluster metadata on the metadata store (e.g., ZooKeeper). You need to initialize it **only once**.`.

- Some docs are missing.

Pulsar API docs has nothing but the "reference". It shows only brief descriptions, commands, and flags and does not contain context (Who/What/Why/When/Where/How/How much), guides, tutorials, examples, demos, etc.

- Some docs are placed incorrectly.

For example, some "Concept"-type docs should be located elsewhere (e.g., Terminology, Messaging, etc.) in Pulsar docs.

- Some docs are in chaotic order.

For example, there are [a lot of operations for Topics](https://pulsar.apache.org/docs/2.10.x/admin-api-topics/), presented in random order. I'll categorize operations logically to match users' learning paces and classify operations based on the CRUD sequence.

- Some docs are redundant.

- Some links are incorrect and invalid.

### ☘️Goal

Based on the [[2022 Report] Pulsar Website Content Analysis (GA)](https://docs.google.com/document/d/1H-wEEfut18M18dle6a4-2EWCnLOqyJ81RVYxkPkTXhk/edit), the Pulsar API doc is one of the top-viewed content. However, Pulsar API was not systematically and logically explained.

This PIP aims to improve the developer experience and take Pulsar API docs to the next level by:

- Correcting inaccurate docs

- Adding more context (Who/What/Why/When/Where/How) docs

- Optimizing/consolidating the existing docs

### ☘️Implementation

Due to the limitation of the GitHub issue review/comment feature, I've recorded all my thoughts in [Google Doc](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.bhlu6hsmx1gp) first, where you can leave suggestions and interact with me more conveniently. I'll keep all comments and conversation history.

If you want to know the details, feel free to click the links below.

================ ✅ [Design thinking](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.hft5gou63k60) ================

The whole design of Pulsar API content is user-centered based on the [Elements of User Experience](https://www.educative.io/answers/what-are-the-five-elements-of-ux-design) because:

- DX can be an extension of general UX, which emphasizes the developer and their experience working with Pulsar APIs.

- Pulsar API doc should be a product in its own right, not just a supplement of "The Product" (Pulsar).


================ ✅ [Design process](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.83rbgh1twask) ================

It includes the following parts:

1️⃣ Strategy
- [Product objectives](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.5lwmi9pz9u1d)
- [User needs](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.l5sjkmuzk8i5)
- [Understand target audiences](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.b2dswnlxw8q5)
- [Pulsar API users](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=kix.2ttjjn5z1ovo)
- [Map out user journey](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.oerex0i48rcv)
- [Why map out user journey?](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.pgyfom8mm992)
- [How to map out user journey?](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.qcd4jh8vf52i)
- [What is Pulsar user journey?](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.fd7n58fyof04)
- [Pulsar user journey stages and API content](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.xgnk69nwtqi)
- [Commonalities of users in API learning](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.cxspxu504pzu)

2️⃣ [Scope (content requirements)](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.f5eqbl6mo5n4)

- [Quantitative analysis (content inventory)](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.778n8257l761)
- Current content
- Content gaps
- Root causes

- [Qualitative analysis (content audit)](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.ppn8qwgapai6)

3️⃣ [Structure (information architecture)](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.y0c06e545eke)
- High-level organization
- General guidelines

4️⃣ [Skeleton (navigation)](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.j2j24p3zt9b)

5️⃣ [Surface (sensory)](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.q0nmyta5m27b)

This needs to cooperate with UI/UX/design teams.
It's out of scope temporarily since this PIP only focuses on doc updates.

================ ✅ [Task status](https://docs.google.com/document/d/1NWmfDyIyUGzXOqX8V28AHyORF72lTFIvxlM6n86wAfU/edit?pli=1#bookmark=id.6soebl1lbvj0) ================

- Doc issues and corresponding changes
- Implementation timeline and task status

Start with the linked research document and the Pulsar 2.10.x API documentation, especially admin-api-overview, admin-api-clusters, and admin-api-topics. Review the documented content gaps and proposed structure before making changes. Done means inaccurate, missing, misplaced, redundant, disordered, and invalid API documentation has been systematically addressed.

Written by the indexing model from the issue text.