Make the Operations guide task-oriented

[dwelsch-esi]

Overview

The Operations Guide should contain instructional content (tasks, procedures, tutorials) for admins looking set up a production etcd service. In general, rewrite instructional sections in this guide to be step-by-step tasks. Move reference material into an omnibus reference section or into a reference section at the end of the Operations Guide.

Split the Operations guide into two parts for two distinct user roles: one for Operators of standalone installations of etcd, one for Kubernetes Admins using etcd as a backing store. Link from/to page rather than duplicating information common to both. Similarly, link from/to the Kubernetes project documentation in the etcd Kubernetes Admin docs to avoid duplicating documentation if practical; however, duplication is preferable to leaving something undocumented.

Audience: Operator; Kubernetes 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/tree/main/content/en/docs/v3.5/op-guide

Following are comments on the existing sections within the Operations Guide.

Issue: Authentication guides > Authentication

Incomplete. Write as a procedure.

Configuration options

Move to Reference section.

Transport security model

Rename to "Setting up transport layer security".

Clustering guide

Consider breaking up into one page per procedure.

Failure modes

This is conceptual information. Consider moving to the system overview. What to actually do in case of a failure, for example the following "Disaster recovery" section, should be in the Troubleshooting section.

Disaster recovery

Move to the Troubleshooting section.

Hardware recommendations

This is a system prerequisite. Create a Prerequisites page in the Cluster Installation section.

Maintenance

Consider providing a more specific, task-oriented title like "Maintaining a cluster".

Design of runtime reconfiguration

Move conceptual information from this page to the architecture overview. Replace this page with a procedure ("Reconfiguring a running cluster").

Supported platforms

Combine with Hardware recommendations in a System Prerequisites section.

Versioning

Rename to "Versioning policy". Move to the top of the version list. Put a link to this version policy in every Release notes.

Add a documentation versioning policy that describes when a new version of the documentation is written (major releases?); when documentation is updated instead (minor releases?); when release notes are written (major and minor releases but not patches?); and when documentation is archived.