PulpCon 2023: Pulp Pain Points

  • Add your (least) favorite pain here!
  • Documentation (too much, too little, not all in one place, oh my!)
    • installation docs!!! Argh!
    • workflows - inconsistent, incomplete
    • comment: "Our documentation holds us back significantly"
    • "docs are good for some things" - but "getting started" is Not Good
      • try this: start from an empty machine, and use the docs to get a running Pulp instance up (that is not in oci_env). Be Sad.
      • LOTS of blocks-of-text
    • ggainey: would be cool to have a "quick start" way to get from empty-machine to "reasonably well-configured pulp instance, with CLI working, and some content"
    • pedro: https://diataxis.fr/
    • RST is hard to grasp.
    • dkliban: docs aren't all in one place
      • plugin-docs are their own little site
      • even the L&F are different
      • Conway's Law
      • so what's an answer?
        • even if plugins are separate, everything on one site that can be searched from one place
      • self-contained plugins ends up reproducing pulpcore info (which can get out-of-date)
      • how does this interact with plugin-versions happening on diff schedule than core-schedule? ("poorly")
    • quirin: federated plugin docs are actually useful
      • operations/settings/installation Isn't That
      • specific settings are for plugins - "how to change the settings", isn't
      • "how to" for, say, "how to deal with single-container"
    • admin-workflows want to be in one place
    • mdellweg: plugin docs are good for workflows and specific setup/cfg-settings
      • anything else - should point to a unified Place
    • bmbouters: would like to push for "one site", period
    • bmbouters: part of why we're in the current state, is docs have-been/are often not "First Priority"
      • contention: we should start focusing on docs/onboarding, more than adding new features, if we want to make the project "better" for new users
    • sherr: +1 top all of the above, BUT…
    • sherr: similar situation for developers
      • project site - not findable from there
      • docs on how to write tests
        • examples are nice
        • pytest is "magic" in a lot of ways
    • ggainey: two hats on two axes:
      • initial contact, "just admin" vs "developer"
      • advanced usage, "admin"/"dev"
    • ipanova: not a great job describing real-world use cases/workflows
      • ggainey: missing the "why"
      • dkliban: recipes used to be pulp2
    • dkliban: JOB 1 needs to be "coherent, clear, consistent installation guide"
    • bmbouters: clearly, a LOT of opportunities identified
      • BUT - needs to be a project-goal
    • sherr: "A doc on how to contribute to docs" is actually a fine, FINE idea
      • right now - who knows?!?
    • bmbouters: having a "docs-person" is not an answer
      • only we, the Pulp team, can fix/address this
    • lmjachky: community manager was actually really valuable
    • decko: can we fire up a docs-taskforce?
    • bmbouters: it's not about stopping feature development - it's about raising the bar on accepting new features
    • x9c4: getting docs written is one thing, keeping them up-to-date/maintained is its own issue
      • prob needs a miniteam to keep us up-to-date
    • bmbouters: the discussion is great, but progress needs a shift in mindset
      • +1s all around
    • it all comes back to team agreement/norms on "What Are Our Shared Goals"
    • [quba42] Single docs site for all deployment methods
      • Should be feasible
    • [quba42] Single docs site for plugins
      • Probably done later
    • [bmbouter] We can consolidate both docs.pulpproject.org and pulpproject.org into 1 site?
      • Yes, it is possible now
    • [bmbouter] At this point it would be cheaper to do a fresh start than to improve our current docs
      • Write new docs, but involve pulling sections
    • [quba42]
      • There are a lot of good sections of the docs, they can be copied. The problem is largley finding them within the current structure.
    • [dkliban]
      • When describing a feature, list what version it was introduced in.
    • agreed: Create a working group. (wg-docs-overhaul)
  • decko: it would be great to have a WebUI
    • hard to sell as a CLI-only
    • ipanova: building a WebUI, without UI/UX experience, can result in a Bad WebUI - which is worse than none
  • Pulp dev environment
    • Can be difficult to set up for devs new to Pulp
    • Fragile, slow, unwieldy
Select a repo