I think we need a doc like this (very close to this) and I’m so glad you’ve put this draft out. I wasn’t sure of the best venue to give feedback, so I’ll leave some thoughts here. Feel free to incorporate or disregard; it’s really just a bunch of little ideas.
I use the idea of a “toolbox” often when I talk about Pulp3 because it’s got all these parts, but a lot of workflows can be made from that. Perhaps thats a helpful analogy to present up front?
The order of introducing Remotes first, then repositories, then distributions is the right order to me.
I don’t think the idea of plugins is very helpful at an intro level. One thing alternatives to Pulp do really well is present their software as one thing with everything ready to go out of the box. Pulp’s plugin model is an advantage for developers and users alike, but plugins are more about how Pulp’s built practically speaking than something an end user would think about. To me, this doc is about what does pulp do, only when I’ve decided I want to use it do plugins become important.
---- this is all one idea for a new section -----
It might be helpful to call out a use case and then using the language you’ve introduced, i.e. remote, repo, sync, distribute, etc to explain a workflow for that specific use case. For example, here are a few user cases that come to mind:
- PyPI goes down sometimes, so I want an on-premise PyPI to have our servers use that.
- Docker is rate limiting now, so I want an on-premise registry with a pull-through cache capability to solve that.
- I mirror the CentOS and Amazon Linux repos nightly and I want an easy way to store nightly versions of these repos so I can roll back in case a new package breaks my servers.
- We use Ansible and we have some Ansible Collections and Roles that have hostnames and usernames that we don’t want to publish on galaxy.ansible.com.
Anyway, the idea with ^ is to put out an undisputed, common problem and easily show how the toolbox solves it. Each ^ would come with a probably numbered steps, e.g. for the PyPI mirror:
- make a remote to sync all of pypi
- make a repository
- configure it to sync nightly
- configure pip on my servers to pull from pulp instead of PyPI.
----- end of new idea ---------
For the CI/CD section, that’s kind of like one of ^ use cases in a way. To me, I think we need to make it more concrete by using a specific CI/CD in the example. Github Actions (GHA) seems to be pretty dominant now (to me) so if we could rework the example to have artifacts produced by CI/CD push into a Pulp server for storage and testing that would allow builds to be tested post-run for example. Or having the CI/CD pull from the Pulp server hosting artifacts. From a high level, I believe telling the story in a specific and concrete (with full examples) way would impact more folks than the generalized version. To get there, I suspect pairing up with a developer to provide that end-to-end example with GHA would be something a dev can do and you could help tell the story in a better way than an engineering written technical doc would.
The under the hood section is good. It serves a different kind of purpose so I wonder about making it, it’s own section? I like this section a lot though. Maybe it should stay with the rest of this content perhaps?
Side-note: for the under the hood section, I want to try to have Redis be fully optional. Even with 3.16 it’s not optional but we’re going to fix that very soon (it’s a bugfix).
For the high availability I think that could be its own article. To me, users just getting started want to know HA is a solved problem but not much more. Then again when users sit down to actually perform an HA config they need more than this section has (I think maybe your other section has all the details in the docs?) Anyways I think shortening this section so folks know it’s a solved problem and here’s how to learn more would allow the rest of the content to stand out more.
Thank you so much for this! Even if this article didn’t change one word I think it’s very good.
thanks 