Newdocs Live Roadmap

What is this?

TLDR: Not intended to be an big-upfront roadmap, but to be build on-demand.

On PulpCon 2023 we've decided to form a workgroup to improve the documentation experience for the Pulp Project. There were a lot of great ideas and considerations about that topic, and the first effort was to narrow down the project scope and set some achievable goals.

The most important thing was about setting up a unified docs, so that's the "Part 1" of the efforts of improving the docs. Nevertheless, the ideas won't stop comming, and that's why this document exists: to capture and organize those ideas into a broader priority plan.

WIP Roadmap

Part 1: Unifying the docs

• Goal: move to an unified documentation that makes sense
• Design Docs: https://hackmd.io/@pbrochad/SyfGeQc86
• Timeline: 11/2023 - 03/2024
• Core team: Brian, Decko, Dennis, Grant, Pedro

Part N: ?

• Goal:
• Design Docs:
• Timeline:
• Core team:

Improvement ideas

• REST Api Documentation usability issue:
  • The problem is that {foo-href} is confusing (instead of full/end/point/{foo-href})
  • What to do?
• Make doc contributions easy:
  • Have a “edit me” buttons on the doc site to submit docs-PRs
  • Allow contributing to docs without needing a fully-running dev-env
  • Add more pre-commit (pre-PR?) linting tools to let machines do their job
    • Should avoid some avoidable review corrections and make the process smoother.
    • See ddavis experiment with hooks.
• Individual Versioning:
  • Add "Version" button to each page and fetch any (or pinned) versions from corresponding repo.
  • Why? This should make handling versioning very convenient for both developers and users.