Project

Profile

Help

Issue #8477

As a new Pulp user, I would like well-described getting started information about using the Pulp installer

Added by mcorr 6 months ago. Updated 4 months ago.

Status:
CLOSED - CURRENTRELEASE
Priority:
Normal
Category:
Installer
Sprint/Milestone:
Start date:
Due date:
Estimated time:
(Total: 0:00 h)
Severity:
2. Medium
Version:
Platform Release:
OS:
Triaged:
Yes
Groomed:
No
Sprint Candidate:
No
Tags:
Documentation
Sprint:
Quarter:

Description

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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.


Subtasks

Issue #8550: Mismatch between pulpcore instructions on pulp_installer and the pulp_installer docsCLOSED - CURRENTRELEASEmcorrActions
Issue #8551: pulp_installer docs do not list system requirementsCLOSED - CURRENTRELEASEActions
Issue #8552: pulp_installer docs need a better explanation of variablesMODIFIEDmdepaulo@redhat.comActions

Associated revisions

Revision b49b958f View on GitHub
Added by mcorr 6 months ago

Add requirements, clarify var usage

fixes #8477

Revision b49b958f View on GitHub
Added by mcorr 6 months ago

Add requirements, clarify var usage

fixes #8477

Revision e2642468 View on GitHub
Added by mcorr 6 months ago

Be explicit about Pulp installer doc

fixes #8477

History

#1 Updated by mdepaulo@redhat.com 6 months ago

  • Assignee set to mdepaulo@redhat.com
  • Triaged changed from No to Yes

#2 Updated by pulpbot 6 months ago

  • Status changed from NEW to POST

#4 Updated by mcorr 6 months ago

  • Status changed from POST to MODIFIED

#6 Updated by dalley 4 months ago

  • Sprint/Milestone set to 3.13.0

#7 Updated by pulpbot 4 months ago

  • Status changed from MODIFIED to CLOSED - CURRENTRELEASE

Please register to edit this issue

Also available in: Atom PDF