Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Umbrella Issue: CNCF Tech Doc Recommendations #766

Open
1 of 14 tasks
Tracked by #221
dwelsch-esi opened this issue Feb 13, 2024 · 1 comment
Open
1 of 14 tasks
Tracked by #221

Umbrella Issue: CNCF Tech Doc Recommendations #766

dwelsch-esi opened this issue Feb 13, 2024 · 1 comment
Labels
enhancement New feature or request help wanted Extra attention is needed

Comments

@dwelsch-esi
Copy link
Contributor

dwelsch-esi commented Feb 13, 2024

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

✏️ 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.

✏️ Write Linux installation instructions

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

✏️ 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.

✏️ 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.

✏️ 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.

✏️ 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 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.

✏️ 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.

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

✏️ 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.

✏️ 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.

✏️ 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.

✏️ 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.

@dwelsch-esi
Copy link
Contributor Author

/cc @nate-double-u

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

2 participants