Create an overview of the installation procedure #4120
Conversation
github-actions
bot
added
Needs tech review
AkshayGadhaveRH
removed
Needs tech review
|
The PR preview for 6783e24 is available at theforeman-foreman-documentation-preview-pr-4120.surge.sh The following output files are affected by this PR: |
|
Working on fixing the build issues. Not ready for review yet. |
AkshayGadhaveRH
force-pushed
the
add_installation_overview
branch
from
8fb89ed to
c05e6d7
Compare
AkshayGadhaveRH
added
Needs style review
Adding a module for installation overview with high level steps and links to each step. JIRA: https://issues.redhat.com/browse/SAT-30834
AkshayGadhaveRH
force-pushed
the
add_installation_overview
branch
from
c05e6d7 to
6783e24
Compare
AkshayGadhaveRH
added
the
Needs tech review
| .Planning | ||
| Make sure that your infrastructure meets the prerequisites for installation: |
There was a problem hiding this comment.
Discrete headings (like .Planning) will eventually be reported as issues by asciidoctor-dita-vale so it would be good not to add new ones. Thinking about how to make this section flow naturally, one option might be this:
| .Planning | |
| Make sure that your infrastructure meets the prerequisites for installation: | |
| During planning, you will make sure that your infrastructure meets the prerequisites for installation. | |
| This includes the following actions: |
This is just a quick suggestion, feel free to tweak it :) The changes I'm making are:
- Replacing discrete heading with a descriptive "During planning, (...)". This adds more words but avoids the need for the discrete heading.
This includes the following actions:helps prevent potential future situations when a new "action" might be added to planning but noone updates this list. (I'm not sure about the word "action" to be honest.)
What do you think? If this sounds good, can you look into updating the other discrete headings in a similar way? Whatever wording you choose, they should all be consistent.
| Make sure that your infrastructure meets the prerequisites for installation: | ||
|
|
||
| * Ensure your hardware and software meet the minimum requirements for CPU, RAM, and storage space. | ||
| * Plan your network setup, including DNS resolution and port/firewall configurations. |
There was a problem hiding this comment.
| * Plan your network setup, including DNS resolution and port/firewall configurations. | |
| * Plan your network setup, including DNS resolution and firewall configurations. |
|
|
||
| * Ensure your hardware and software meet the minimum requirements for CPU, RAM, and storage space. | ||
| * Plan your network setup, including DNS resolution and port/firewall configurations. | ||
| * For large deployments (e.g., more than 5,000 hosts), select a predefined performance profile to optimize your system. |
There was a problem hiding this comment.
| * For large deployments (e.g., more than 5,000 hosts), select a predefined performance profile to optimize your system. | |
| * For large deployments of more than 5,000 hosts, consider whether to use a predefined tuning profile to optimize {Project} performance. |
The changes I'm proposing are:
- Drop "e.g."
- Phrase this action as optional ("consider") rather than required ("select")
- Clarify that it's {Project} that's being optimized, not really "the system"
|
Speaking in more general terms, this request came from Red Hat's downstream. In upstream, I've been mostly hearing about concerns that the installation guide is very long, which doesn't work well for upstream users. Therefore, I'm wondering: Should we only include the new overview for Satellite to address the downstream need, while excluding it from upstream to better accommodate the upstream users' needs? |
IMO there's value in this overview, so I am OK with adding it for all flavours. |
|
|
||
| * Install the {Project} package and all its dependencies. | ||
| * Use the `{foreman-installer}` command to perform the initial server setup. | ||
| * Import your subscription manifest. |
There was a problem hiding this comment.
If we're rendering the overview for all builds, this needs to be hidden for foreman-{el,deb}
| .Server preparation | ||
| Configure the operating system and the repositoties for installating {Project}: | ||
|
|
||
| * Install {EL} 9 on a freshly installed system. |
There was a problem hiding this comment.
If we're rendering the overview for all builds, this needs to be changed for foreman-deb to Debian 12 or Ubuntu 22.04 or something.
| [id="overview-of-the-installation-process"] | ||
| = Overview of the installation process | ||
|
|
||
| The {Project} installation process can be broken down into three main phases: |
There was a problem hiding this comment.
| The {Project} installation process can be broken down into three main phases: | |
| The {Project} installation process consists of the following main phases: |
Adding a module for installation overview with high level steps and links to each step.
JIRA: https://issues.redhat.com/browse/SAT-30834
What changes are you introducing?
Why are you introducing these changes? (Explanation, links to references, issues, etc.)
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
Contributor checklists
Please cherry-pick my commits into:
Review checklists
Tech review (performed by an Engineer who did not author the PR; can be skipped if tech review is unnecessary):
Style review (by a Technical Writer who did not author the PR):