dwelsch-esi
commented
8 months ago /cc @nate-double-u
We should probably push the analysis PR now that it's referenced in this issue.
Open dwelsch-esi opened 8 months ago
dwelsch-esi
commented
8 months ago /cc @nate-double-u
We should probably push the analysis PR now that it's referenced in this issue.
☂ 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: https://github.com/cncf/techdocs/issues/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:
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.