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?
    • maybe just to set direction/organization approach?
    • ipanova: we've been here before
      • unless something changes - why do we think this will work better now?
      • https://discourse.pulpproject.org/t/pulp-docs-sig-findings-conclusions-software-repository-management/372
    • decko: can't be the same people all the time
    • bmbouters: prev working-group was good at setting up a plan, couldn't get focus/implementation
  • 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