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, which serves as supplementary material to understand why and how we resolve this issue.

☘️Motivation

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. 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, 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), 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 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 ================

The whole design of Pulsar API content is user-centered based on the Elements of User Experience 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).