ECE installation docs consolidation

[eedugon]

Description

During the docs migration we found out that the ECE installation docs would benefit from some structural improvements to make everything clearer and easier to users.

We didn't have time to implement the changes, so we are reporting here the details of the proposal for a future improvement. Feel free to reach out for more details, if needed.

Resources

The way ECE installation docs have evolved has ended up in siloed docs that are linked and related in a not very clear way.

• On one side we have 3 different installation documents called small, medium and large installation docs.

  • We already have the different sizes of environments with their characteristics presented in the document called Identify your deployment scenario. That doc has the same images and information than the 3 install docs.
  • Considering the installation commands and procedure is almost the same (with different memory settings for example and different roles) ideally we should have a single / main installation document. With the new docs system this could be easily accomplished using tabs to propose different memory settings or roles, and describing the recommended JVM memory settings depending on the size of the installation the same way as the current 3 docs are doing.

• Secondly we have the air-gapped instalallation docs: Those docs are actually about using a private docker registry or downloading the docker images, and when it comes to the installation command itself we just mention the parameter to use when installing --> Our main installation document should just cover this use case, and show what installation parameter should be used in air-gapped environments (assuming the private registry or images have been setup). And the Air-gapped install section of the documentation should focus on the environment setup (registry, etc) and not on the install command itself.

• Finally we have the podman based installation: we have a completely different document just to tell users to use the --podman flag during the installation (where everything else is the same). -> The main installation document should also cover podman use case.

• On top of all that, certain notes and hints that some of the side documents mention (like podman or air-gapped) are totally valid for all installation docs, which creates confusion like is this recommendation only applicable to podman? why the standard installation doc doesn't include it?

Objective
Instead of having 5 different installation documents (which creates a lot of confusion), make it a single installation document with clearer instructions for all use cases and environments, providing examples and using tabs when necessary.

Extra improvements

• We should also consider using snippets when possible to not duplicate content.
• And the OS configuration guides should be reviewed with that in mind (check if some snippets would be useful).
• Analyze the guide called Migrate ECE to Podman hosts to see how it would fit with the new installation documents and the OS configuration guides. That guide has a huge amount of duplicated information that could get outdated. Consider using snippets if the steps are the same as in the Configure OS guide, or link to the guide.
• Ansible install document -> it's such a small document that it could be a sub-section of the main installation doc.

Which documentation set does this change impact?

Elastic On-Prem only

Feature differences

N/A

What release is this request related to?

N/A

Collaboration model

The documentation team

Point of contact.

Main contact: @eedugon

Stakeholders: @shainaraskas