Search before asking
What issue do you find in Pulsar docs?
This idea popped up when I was thinking about how to improve the client libraries docs - it's very likely that because we haven't got a robust and structured topic-based authoring model to host the docs for various features, contributors/maintainers don't know what's the proper place to fit the information in so they keep tiling the content in clients' docs, which causes many duplicates and inconsistencies, and somehow isolated and difficult to consume. So I started with Security doc improvements and now Schema.
Schema content is scattered and not easy to read and understand, including:
- The overall Information Architecture can be better organized and reused.
- Similar to the Security - authentication section, the schema examples and references for multi-language clients can be incorporated into the Schema chapter and only keeps a link in the
Client Libraries chapter. ---- also has a dependency on this client doc issue.
- Administrative tasks using APIs should be relocated to the
Admin Interfaces chapter.
- Outdated content needs a revisit and refresh.
What is your suggestion?
- Redesign the information architecture through content mapping. The following is an initial thought. Feel free to leave your suggestions regarding schema content, as a user or an expert.
2. Improve the content with engineering experts in a follow-up PR.
Any reference?
The applied methodology and expected outcome for refactoring the IA and content are similar to the following chapters:
Are you willing to submit a PR?
Implementation
Search before asking
What issue do you find in Pulsar docs?
This idea popped up when I was thinking about how to improve the client libraries docs - it's very likely that because we haven't got a robust and structured topic-based authoring model to host the docs for various features, contributors/maintainers don't know what's the proper place to fit the information in so they keep tiling the content in clients' docs, which causes many duplicates and inconsistencies, and somehow isolated and difficult to consume. So I started with Security doc improvements and now Schema.
Schema content is scattered and not easy to read and understand, including:
Client Librarieschapter. ---- also has a dependency on this client doc issue.Admin Interfaceschapter.What is your suggestion?
2. Improve the content with engineering experts in a follow-up PR.Any reference?
The applied methodology and expected outcome for refactoring the IA and content are similar to the following chapters:
Are you willing to submit a PR?
Implementation