# 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
*