Project

Profile

Help

Issue #8477

closed

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

Added by mcorr over 3 years ago. Updated over 3 years ago.

Status:
CLOSED - CURRENTRELEASE
Priority:
Normal
Category:
Installer - Moved to GitHub issues
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.


Sub-issues 3 (0 open3 closed)

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
Actions #1

Updated by mdepaulo@redhat.com over 3 years ago

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

Updated by pulpbot over 3 years ago

  • Status changed from NEW to POST

Added by mcorr over 3 years ago

Revision b49b958f | View on GitHub

Add requirements, clarify var usage

fixes #8477

Added by mcorr over 3 years ago

Revision b49b958f | View on GitHub

Add requirements, clarify var usage

fixes #8477

Actions #4

Updated by mcorr over 3 years ago

  • Status changed from POST to MODIFIED

Added by mcorr over 3 years ago

Revision e2642468 | View on GitHub

Be explicit about Pulp installer doc

fixes #8477

Actions #6

Updated by dalley over 3 years ago

  • Sprint/Milestone set to 3.13.0
Actions #7

Updated by pulpbot over 3 years ago

  • Status changed from MODIFIED to CLOSED - CURRENTRELEASE

Also available in: Atom PDF