Revise the installation guide

[dwelsch-esi]

Overview

In the introduction to the installation instructions, briefly describe why a user should prefer using one installation procedure over another. Distinguish between production installations and local clusters for development or demo purposes. Include a link to the page for setting up a local cluster.

Consider separating the install procedures and putting each on its own separate page.

Audience: Standalone Operator

Type: Task

The existing documentation might contain helpful source material that you can pull into this doc change. See recommendations for the existing (at the time of the CNCF tech doc analysis) etcd technical documentation pages:
https://github.com/cncf/techdocs/blob/main/assessments/0010-etcd/etcd-implementation.md/#general-reorganization

🎤 Context

This issue tracks recommended changes resulting from an analysis of the etcd documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/assessments/0010-etcd/

✌️ Possible Implementation

Related material in the current doc:

• https://github.com/etcd-io/website/blob/main/content/en/docs/v3.5/install.md

[ronaldngounou]

How is this task different from Issue 782 ?

It seems like this task is being partially addressed in my PR.

I read the CNCF tech doc. To my understanding, issue #770 and issue #782 overlap.

@dwelsch-esi Could you please guide me to which information I could integrate on top of my my PR in order to close this issue?

After receiving further clarifications, I will work on this. ✋🏽

[dwelsch-esi]

@ronaldngounou Good questions. I think they all address the same basic issue, which is that the quick start and installation documentation are related but different documents with different purposes.

The goal of the quick start is to get a working instance of the software running as quickly as possible. Usually this is a pared-down version: a local installation, a single-node instance of cluster software, that sort of thing. Other characteristics of a quick-start installation:

• Often this installation is suitable for a demo or for development, but rarely is it suitable for production.
• There might be some assumptions, such as a particular OS or installation method (a container image, for example, or a package-managed install). It's never built from code.
• It's a one-size-fits-all install. If the user has an unusual platform or needs a feature not found in the quick-start version, they have to use a different install.
• The quick start guide is short and contains simplified instructions.

In contrast, the installation guide provides comprehensive coverage of all installations. It must provide complete install instructions for every supported scenario:

• There must be procedures for installing using every supported package manager, container solution, and build-from-scratch option.
• If there are differences between installations for different user roles (developer vs production installation, for example) these must be documented separately.
• A common mistake is to try and cover too many install scenarios in one procedure. If there are any significant differences at all between two installations, document them separately and explain the differences to the user so they can pick the right one for them.
• The installation guide is as long as it needs to be to explain all the install options.

Does that make sense? The two separate issues address the needs of these two separate documents. The installation instructions can sometimes be partially addressed by the quick start guide, but only if the quick start scenario happens to be one of the installation scenarios (a local install suitable for development, for example). And only if it doesn't make simplifying assumptions that limit the user's choices.

Looking at issue #782, I see that I've recommended writing quick starts for both development and operations paths. I'm not sure that's necessary as long as both paths are addressed in the installation instructions.

Hope that helps. If you have any other questions I'm happy to try and help. Also, I discussed this with @chalin at one point and he might have some guidance as well.

[ronaldngounou]

Your explanations on the quickstart section make sense. I believe I done that in this PR.✅

It makes sense. I will elaborate more on the installation steps.

I suggest this structure:
H1: Installation Guide
a) Installation procedure in a production environment (link to installation on Kubernetes ?)
b) Installation procedure as an application developer (link to Quickstart)

H2: Requirements
H2: Install pre-built binaries. I will detail the step 2 and step 3.
H2: Build from source: clarify step 1 and step 4.
H2: Running etcd as a service inside Kuberenetes
H3: Helm Installation
H3: Using YAML Manifests

/assign

[dwelsch-esi]

@ronaldngounou Which installation are the requirements in the first H2 for? I'd recommend writing prerequisites for each install procedure, even if they're similar:

H2 Install pre-built binaries
H3 Prereqs
H3 Procedure
H3 What's Next
H2 Build from source
H3 Prereqs
H3 Procedure
H3 What's Next
H2 Running as a K8s service: Helm install
H3 Prereqs
H3 Procedure
H3 What's Next
H2 Running as a K8s service: YAML manifests
H3 Prereqs
H3 Procedure
H3 What's Next

I know this seems redundant, but the goal is to give the user an easy instruction path for whichever install they choose.

I'd also consider putting each install procedure on its own page and linking from an Installation landing page.