Umbrella Issue: CNCF Tech Doc Recommendations

[dwelsch-esi]

☂ Overview

This is a checklist for the CNCF technical documentation analysis and implementation plan. It should be updated as sub-issues are added, completed, or otherwise modified.

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/

The CNCF etcd documentation effort is tracked in the CNCF Tech Docs repo:
cncf/techdocs#191

🗞️ Sub-issues

This is a list of issues representing the recommended work on the etcd website and technical documentation.

✏️ Describe etcd's user roles

In an "Overview" or "Start here" page, outline etcd's user roles or personas, including:

• Evaluator: Someone trying to determine whether etcd is appropriate for their product, project, or organization.
• Admin or Operator: Someone reponsible for setting up and maintaining a standalone (non-Kubernetes-backstore) production etcd service.
• Kubernetes Admin: Someone responsible for a Kubernetes cluster using etcd as a backstore.
• Developer: Someone incorporating or integrating etcd into an application or service.

In each user role section, provide a link to the beginning of a "getting started" workflow, either a Quick-start or Installation instructions.

• Describe etcd's user roles #780

✏️ Convert tutorials to tasks

Rename the "Tutorials" section "Tasks". Split this Task section by user role and put the resulting two sections in their respective user guides: Developer and Operations.

• Convert tutorials to tasks #765

✏️ Write Linux installation instructions

Write the installation instructions marked "TBD" at:
https://etcd.io/docs/v3.5/install/#linux

• Write Linux installation instructions #767

✏️ Write Kubernetes installation instructions

Write the procedure Installation as part of Kubernetes installation, or link to Kubernetes documentation that includes etcd installation as backstore. Explain and fill in (on the etcd docs page) any gaps in the procedure.

• Write installation instructions for Kubernetes #781

✏️ Update quickstart and new user workflows

Rename to "Quick start" (two words). Add a "Prerequisites" section and revise the "What's next" section to focus on two separate paths, Development and Operations. Write separate "Getting started" workflows for Developer and Operator users. For the developer path, link to the "Set up a local cluster" page rather than the install page.

• Update quickstart and new user workflows #782

✏️ Consolidate reference information

Consolidate all reference information to a reference-specific section.

Or, create user role-specific reference sections within the Developer and Operations guides. Since some of the material overlaps, a single reference section is probably easier.

Reference documentation includes API, CLI, and configuration references, the glossary -- any topic that presents a comprehensive "lookup" document.

• Consolidate all reference information #768

✏️ Make the Developer Guide task-oriented

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 Developer Guide. (See separate issue concerning reference section.)

• Make the Developer Guide task-oriented #769

✏️ Make the Operator Guide task-oriented

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.

• Make the Operations guide task-oriented #783

✏️ Revise the installation guide

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.

• Revise the installation guide #770

✏️ Create a System 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".

• Create a System Overview #771

✏️ Relocate Benchmarks

This section is mostly redundant with Benchmark section in Operations guide > Performance. Move any non-redundant info to the Performance section in the Operations Guide.

Remove old benchmarks if they're no longer needed.

• Relocate Benchmarks #772

✏️ Update the Upgrading landing page

The "Upgrading etcd clusters and applications" page seems redundant. The "Upgrading" link could goes straight to the main upgrade page, which contains the same information. There's no need to ever visit the Upgrading etcd clusters and applications page.

It might be worthwhile to do a little research and remove or archive unneeded and unsupported upgrade pages. Also, is an upgrade path over more than one point release supported? If so, does it require a series of upgrades, such as for example 3.3 > 3.4 > 3.5? If so, state this explicitly on the "Upgrading" landing page. If not, document the supported paths.

• Update the Upgrading landing page #773

✏️ Reorganize the documentation

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.

• Reorganize the documentation #784

✏️ Revise the FAQ

The longer explanations in the FAQ might be better as part of conceptual information -- for example, in the system or architecture overview. Retain the short answers that don't fit elsewhere. The FAQ can contain links to further information in other sections.

• Revise the FAQ #786

[dwelsch-esi]

/cc @nate-double-u

We should probably push the analysis PR now that it's referenced in this issue.