PIP-228: Refactor Information Architecture of Pulsar Client Documentation

[momo-jun]

• Status: Accepted/Development in Progress
• Author: momo-jun
• Pull Request: [refactor][doc] Refactor the information architecture of client library docs pulsar-site#393
• Mailing List discussion: Discussion, Vote, Staging/Review.
• Release: 3.0.0 (tbd)

Motivation

This proposal is focused on refactoring and improving the information architecture of the existing Pulsar client documentation. The benefits it can bring include:

• Improve the developer experience and help them get started by offering bite-sized basics.
• Build a solid content structure to make the doc set easier to increment and scale.
• Contribute to decision-making and Pulsar adoption.

Goal

The following major issues of Client docs can be improved in terms of information architecture.

• The Client concepts topic does not introduce the basic client concepts and can be enriched with content relocated from other topics.
• Feature concept topic, e.g., messaging, also includes concept/reference information of clients that should have been decoupled. For example, the content of Producers/Consumer and their attributes (send/access/receive modes) belongs to the scope of Client concepts.
• The structure of Pulsar client library docs (e.g., Java client) also compiles everything in one page:
  • Lack of information typing/sorting - various types of information are coupled together, which makes it difficult to navigate and digest.
  • Redundant: each client’s doc page somehow mirrors a few basic/advanced dev tasks for specific Pulsar features - overlapping feature IA and contents. Being isolated from feature contents (without single-sourcing) also makes updates easier to be missed when incremental improvements are implemented for feature contents.
    In a nutshell, keeping the IA as is will make client doc more complex in both reading/consuming and developing/maintaining, especially when it scales with more features/supports added in the future.

In a nutshell, keeping the IA as is will make client doc more complex in both reading/consuming and developing/maintaining, especially when it scales with more features/supports added in the future. The goal of this PIP is to tackle this challenge by applying the following strategies:

• Make the overall content well-organized, bite-sized, and robustly linked.
• Curate a Get Started section for language-specific clients with minimum basics, such as installation, hello world examples, and links to more topics, which can be advanced dev tasks, feature contents, feature matrix, etc.
• Curate a couple of new topics to introduce advanced dev tasks regarding working with clients.

Implementation

The following figure shows an example of the IA redesign work BEFORE & AFTER.

Key changes

• Concept, task, and reference types of information for Pulsar clients are well categorized and linked.
• The structure of Client Libraries is simple and straightforward to get developers started, from installations to hello world, with rich links only to more advanced tasks and feature contents. All topics are task-oriented with a clear purpose around using Pulsar features and branching into different languages.
• The new IA also enforces the same substructure of dev tasks to introduce how to work with language-specific clients with a sense of consistency. Language-specific code snippets are displayed via tabs.

Task Breakdown

• Implement the IA changes with content mapping
• Update doc and add incremental changes to align with code
• Curate an independent page for the client-feature matrix (PIP-199)

Reference

• Examples of client library docs: Aerospike client library docs can be a real-world example of what this proposal will direct to.
• Preceding works that relocate a couple of redundant dev tasks with examples to refactored feature docs:
  • [refactor][doc] Refactor the information architecture of Schema topics #18242
  • [improve][doc] Improve the information architecture of encryption and cookbook #17666
  • [improve][doc] Improve the information architecture of the security chapter #17615

[github-actions]

The issue had no activity for 30 days, mark with Stale label.

[momo-jun]

Hi bot, this PIP is not stale, but on track and in good health. Sorry for not updating it :)

Attached the links to the follow-up doc enhancements implemented by @RobertIndie :

• Added the missing code examples for using Java - [Improve][doc] Add missing examples for java client pulsar-site#430
• Added how to initialize C++/Python client - [improve][doc] Add initialization doc for CPP and Python client pulsar-site#444
• Added the missing configs for C++/Python/Go clients
• Will add more code examples for C++/Go/Python/Node.js/C# clients

[github-actions]

The issue had no activity for 30 days, mark with Stale label.