You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2022/12/08 12:29:26 UTC
[GitHub] [pulsar] momo-jun opened a new issue, #18822: PIP-228: Refactor Information Architecture of Pulsar Client Documentation
momo-jun opened a new issue, #18822:
URL: https://github.com/apache/pulsar/issues/18822
### 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 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](https://pulsar.apache.org/docs/2.10.x/concepts-clients) topic does not introduce the basic client concepts and can be enriched with content relocated from other topics. See [Proposed IA](https://docs.google.com/document/d/1bVpXUWqp2MEhoaj8d7F7KDlccMjQn4J93qiIMg3jpzs/edit#heading=h.rfc7bs2p81mp) for more details.
- Feature concept topic, e.g.,[ messaging](https://pulsar.apache.org/docs/next/concepts-messaging#compression), 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](https://pulsar.apache.org/docs/2.10.x/concepts-clients).
- The structure of Pulsar client library docs (e.g., [Java client](https://pulsar.apache.org/docs/2.10.x/client-libraries-java)) also compiles everything in one page:
- Lack 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 link 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.
### API Changes
_No response_
### Implementation
The following figure shows the BEFORE & AFTER of the IA redesign work.
**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.
**Reference**
[Aerospike client library docs](https://developer.aerospike.com/client) can be a real-world example of what this proposal will direct to.
### Alternatives
_No response_
### Anything else?
**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](https://github.com/apache/pulsar/issues/17098))
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] PIP-228: Refactor Information Architecture of Pulsar Client Documentation [pulsar]
Posted by "merlimat (via GitHub)" <gi...@apache.org>.
merlimat closed issue #18822: PIP-228: Refactor Information Architecture of Pulsar Client Documentation
URL: https://github.com/apache/pulsar/issues/18822
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] momo-jun commented on issue #18822: PIP-228: Refactor Information Architecture of Pulsar Client Documentation
Posted by "momo-jun (via GitHub)" <gi...@apache.org>.
momo-jun commented on issue #18822:
URL: https://github.com/apache/pulsar/issues/18822#issuecomment-1461207870
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 - https://github.com/apache/pulsar-site/pull/430
* Added how to initialize C++/Python client - https://github.com/apache/pulsar-site/pull/444/
* Will add the missing configs for C++/Python/C#/Go clients
* Will add the missing code examples for C++/Go/Python/Node.js/C# clients
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] github-actions[bot] commented on issue #18822: PIP-228: Refactor Information Architecture of Pulsar Client Documentation
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on issue #18822:
URL: https://github.com/apache/pulsar/issues/18822#issuecomment-1519269888
The issue had no activity for 30 days, mark with Stale label.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] github-actions[bot] commented on issue #18822: PIP-228: Refactor Information Architecture of Pulsar Client Documentation
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on issue #18822:
URL: https://github.com/apache/pulsar/issues/18822#issuecomment-1461158757
The issue had no activity for 30 days, mark with Stale label.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] PIP-228: Refactor Information Architecture of Pulsar Client Documentation [pulsar]
Posted by "merlimat (via GitHub)" <gi...@apache.org>.
merlimat commented on issue #18822:
URL: https://github.com/apache/pulsar/issues/18822#issuecomment-6377559228
Thanks @momo-jun for driving this. PIP-228 was voted on (https://lists.apache.org/thread/5g0mhvks90nx4sh7fnpmkqj6k2dvxjpp), and the new client docs structure landed in apache/pulsar-site#393, with follow-ups in apache/pulsar-site#430, #444, #465, #472 and #479. Closing as completed. Further doc improvements can go to the apache/pulsar-site repository.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org