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:
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.
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:
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.