Reorganize the documentation

[dwelsch-esi]

Overview

Move reference and conceptual topics out of the task-based documentation and into their own (new, if necessary) sections. Write documentation as needed to fill gaps in the conceptual or reference sections.

Audience: All

Type: All

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

Reorganize the documentation to follow this suggested outline:

• Architectural and system overview (Much of the current "Learning" section)
• "Start here" overview:
  • Explanation of user roles and use cases
  • Quick start for each user role
  • Detailed installation and configuration for each user role (Contents of current "Installation" page plus Local cluster install)
• Developer guide
• Operator guide
  • Standalone etcd
  • Kubernetes backstore
• Troubleshooting
• Reference
  • Configuration
  • CLIs
  • APIs
  • Logs and error messages
  • Glossary
• Release notes

The goal is to organize the site around the task documentation so that users can find instructions for what they need to do quickly and navigate there directly. Conceptual and reference information should be separate, and linked where necessary to support this goal.

The following tables contain suggested ToC additions, page deletions, and page moves. Conceptual and task documentation requiring writing or rewriting are described in separate Issues.

Add sections

Sections to be added to the table of contents.

Section	Description
Reference	A library of reference documents: APIs, CLIs, configuration options, and anything else a user might need to look up to complete a task.
Troubleshooting	A list of procedures for diagnosing and fixing problems.
Release Notes	The cumulative release notes for the major and minor release. See Release Notes.

Remove pages

Pages to be removed entirely or cannibalized and their contents integrated elsewhere. Links (listed in the table) will need to be removed or updated as well. If the page duplicates or largely overlaps information on another page, that page is listed as "Redundant with". Page URLs are relative to https://etcd.io/docs/v3.5/.

Page	Links	Redundant with	Suggested action
demo/		op-guide/authentication/authentication/	Remove
dev-internal/discovery_protocol/	op-guide/clustering/	dev-guide/discovery_protocol/	Remove
/dev-guide/interacting_v3/	dev-guide/local_cluster/	tutorials/*.md	Consolidate under "Tasks". See Tutorials
op-guide/recovery/	op-guide/failures/, op-guide/runtime-configuration/, op-guide/runtime-reconf-design/		Incorporate into Troubleshooting guide
op-guide/data_corruption/	op-guide/monitoring/		Incorporate into Troubleshooting guide
upgrades/			Remove or archive old upgrade paths if they're no longer needed or supported.
dev-guide/features/			Remove from the Developer guide. See etcd features.

Move pages

Pages to be moved as-is, usually under an organizing heading. Links (listed in the table) will need to be updated. Page URLs are relative to https://etcd.io/docs/v3.5/.

Page	Links	Suggested action
metrics/		Move to the Operations Guide.
learning/glossary/		Move to Reference section.
tuning/	op-guide/hardware/, quickstart/	Move to the Operations Guide.
dev-internal/logging/		Move to the Reference section. Link from the Operations guide.
dev-internal/modules/		Move to Architecture overview.
integrations/	quickstart/	Move to the Reference section. Consider organizing by user role , or labeling each tool or library by user role.
integrations/#projects-using-etcd	quickstart/	Move to a logo wall or at least to its own page on the website.
reporting_bugs/		Combine with the "Triage" topics and move to the repo's Contributor guide. Link from the Troubleshooting guide.
faq/		Move to near the end of the ToC.
dev-guide/api_reference_v3/	op-guide/runtime-configuration/	Move to the Reference section.
dev-guide/api_concurrency_reference_v3/		Move to the Reference section.
op-guide/container/		Put in the Clustering Guide.
op-guide/configuration/	quickstart/	Put in the Reference section.
upgrades/		Move to the Operations guide.
triage/		Move to the repo and provide a link from the documentation (release notes) to create a cleaner separation of product documentation and project documentation.