Create a System Overview

[dwelsch-esi]

Overview

Rename the "Learning" section to "System Overview" or "Conceptual Overview". This is the place for detailed explanations of the system philosophy, design, and architeture. Edit the content, limiting it to explaining concepts. Move instructional and reference topics to their own areas of the documentation.

Move this new System Overview section to earlier in ToC, perhaps before "Installation".

Audience: All

Type: Conceptual

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

The system overview will have several subsections. The existing subsections are a good start, but don't be shy about adding, consolidating, removing, and renaming sections as needed to best describe the product architecture and design.

Related material in the current doc:

• https://etcd.io/docs/v3.5/learning/data_model/
• https://etcd.io/docs/v3.5/learning/design-client/
• https://etcd.io/docs/v3.5/learning/design-learner/
• https://etcd.io/docs/v3.5/learning/design-auth-v3/
• https://etcd.io/docs/v3.5/learning/api/
• https://etcd.io/docs/v3.5/learning/api_guarantees/
• https://etcd.io/docs/v3.5/learning/why/
• https://etcd.io/docs/v3.5/learning/glossary/
• https://etcd.io/docs/v3.5/dev-internal/modules/
• https://etcd.io/docs/v3.5/op-guide/runtime-reconf-design/
• https://etcd.io/docs/v3.5/op-guide/failures/
• https://etcd.io/docs/v3.5/dev-guide/api_grpc_gateway/
• https://etcd.io/docs/v3.5/dev-guide/grpc_naming/

Suggested changes:

Recommendations follow for the existing subsections of "Learning":

Data model: Include in architecture overview.

etcd client design: Include in architecture overview. Remove the Glossary and merge it into the site-wide Glossary.

etcd learner design: Include in architecture overview. Eliminate references to previous and future releases; describe the current release only. Put comparisons to other releases in the release notes, if relevant.

etcd v3 authentication design: Include in architecture overview.

etcd API: Include in architecture overview.

KV API guarantees: Include in architecture overview. Rename to "Key-value API guarantees".

etcd versus other key-value stores: I think this properly belongs on the webpage as an evaluation tool, but if there's a case for comparing etcd to other KV stores as an instructional strategy, leave it in the system overview. In either case, it needs to be updated.

Glossary: Move to Reference section.