Pulp

After finding this feedback on Reddit, https://www.reddit.com/r/sysadmin/comments/k2nnbr/pulp3_installation/ I started exploring why end users might have problems with our Pulp installer. I think we can make some improvements to the documentation so that users are not lost on the first hurdle.

Here are some of the problems I have identified:

1. On the main Pulpcore docs page, we have a section titled Ansible installer (Recommended) where we have some commands relating to the Ansible installer, but we never explicitly state that we have a more comprehensive set of docs elsewhere: https://docs.pulpproject.org/pulpcore/installation/instructions.html#ansible-installation-recommended If I was a new user, I might disappear at this point for lack of direction. @mikedep333 also pointed out that there is an error in this set of docs. mcorr thinks that it is poor practice to have two sets of docs like this on the go.

We should explicitly state that this is a short introduction to the installer, and ask the users to check out the more comprehensive guide to the installer at the different URL. If these docs are to remain duplicated, we must add a step to the installer release process to check these docs in pulpcore in the weeks leading up to a release.

2. On the pulp-installer docs page https://pulp-installer.readthedocs.io/en/latest/ - a user has no clue about system requirements/hardware requirements. They are not told what to review before they run the installer. We need to link to system requirements in pulpcore from here. We need to be more explicit about all the requirements and considerations users. need to be aware of on their first day installing Pulp. https://docs.pulpproject.org/pulpcore/components.html#hardware-requirements. I think hardware requirements might need more prominent placement in Pulpcore installation docs too.

3. The next section is titled Variables https://pulp-installer.readthedocs.io/en/latest/#variables. Nowhere does it tell users why this is the second topic in the Installer guide. I propose we change this to "Customizing your installation to suit your environment" and give a list of popular and known changes that you can pass through to the Ansible installer via the variables. In this way, the user has been inspired to think about possible options they might need.

4. There is a nice asciinema and other instructions in the Getting Started section. The entire Getting started section should probably be integrated with the landing page of the docs to give a step by step account of what will happen.

5. A checklist should be added to the landing page so that the user has a high level overview of what they'll need to consider to install Pulp.

6. To build a relationship with new users, we should point to where they can get help, where they can post questions, and where they can leave general feedback about the Installation experience so that they are offered an avenue to let us know where we can improve. We should add pulp-list to the docs, and also add a survey form for feedback gathering open at all times.

7. We need to add information about how safe it is to rerun the installer if they get errors. Ideally we come up with a troubleshooting tips and tricks. @mikedep mentioned how the error messages are not very clear, so we should try and give them all the ideas possible to get out of their problem, and if not, where to talk to us.

When all this is done, we should post this to reddit as a solution so that anyone who hits on that site can know the info has been updated.