diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index 6edd2c2..4d33cd5 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -116,7 +116,7 @@ The documentation contains **instructions** for various features. These instruct The documentation contains an adequate introduction and overview, but these are buried in the doc and difficult to find. The adoption path needs more focus and to be split out by user role. For example, "Getting started" should be different for a developer setting up a development server vs. an admin setting up a production server. -The **"happy path"** for etcd is not a simple procedure and, again, varies by user role. However, I believe that there is sufficient documentation of the most common use cases (configure and run an HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. Exception: The Kubernetes and Linux installation instructions noted above. +The **"happy path"** for etcd is not a simple procedure and, again, varies by user role. However, I believe that there is sufficient documentation of the most common use cases (configure and run an HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. Exception: The Kubernetes and Linux installation instructions noted above. Also, procedures for Operators using etcd with Kubernetes (a distinct user role) are a separate path and are at least partially covered in the Kubernetes documentation. Task and tutorial content are **clearly named according to user goals**. Using "-ing" verb forms instead of "How to ..." would make headings easier to navigate. @@ -140,7 +140,7 @@ There is a single paragraph on the [website][etcd-io] landing page with a "Learn There are **install** and **quick start** entries in the technical documentation ToC. These are good starting points but could be refined. User roles are not addressed. -The **installation** page gives step-by-step instructions for installing from binaries, from source, and using a package manager. Installation as part of a Kubernetes installation is also described on the page, but there is a placeholder under the heading "Installation as part of Kubernetes installation". Linux installation is also "TBD", which seems like a big omission. +The **installation** page gives step-by-step instructions for installing from binaries, from source, and using a package manager. Installation as part of a Kubernetes installation is also described on the page, but there is a placeholder under the heading "Installation as part of Kubernetes installation". I understand that etcd installation with Kubernetes depends on how you install Kubernetes, and that in some cases it's automatic and/or documented in the Kubernetes tech doc. In any case, there should be a discussion of the options and links to the relevant Kubernetes docs. Linux installation is also "TBD", which seems like a big omission. Package manager installation is documented (but not recommended) for Linux and MacOS. **Other OSes** are alluded to but not documented. Supported platforms are documented in the [Operations guide](https://etcd.io/docs/v3.5/op-guide/supported-platform/). @@ -203,7 +203,7 @@ For an excellent and very literal example of this approach, see the [Kubernetes Much of the conceptual information about etcd is in the "Learning" section. Rename this section and organize it into a primer on the etcd architecture. Move non-conceptual information elsewhere. -Fill in missing instructional documentation. Most notably, write instructions for installing on Kubernetes and Linux, and on using Authentication. +Fill in missing instructional documentation. Most notably, write (or link to) instructions for installing on Kubernetes and Linux, and on using Authentication. Use "-ing" verb forms instead of "How to ..." as headings for procedures. @@ -244,9 +244,15 @@ Point "Learn more" links to a "Start here" page that provides orientation and se 2. Setting up an environment and testing the server using the CLI. 3. Getting started programming with an API. -Write step-by-step instructions for all installation cases. Clearly describe what each case is for; especially distinguish between development and production installations. +Write step-by-step instructions for all installation cases. (Or, in the case of a Kubernetes Operator user role, links to relevant Kubernetes docs.) Clearly describe what each case is for; especially distinguish between development and production installations. -Revise the Quick Start guide to indicate which user role it's for: developer, operator/admin, or adoption decision maker (it might need to be split into two or more guides). Focus the options in the "What's next?" section to point to a few (two or three) learning paths for specific persona use cases. +Revise the Quick Start guide to indicate which user role it's for: +- developer, +- etcd standalone operator/admin, +- Kubernetes operator/admin, or +- adoption decision maker + +This might require the Quick Start guide to have multiple paths or be split into two or more guides. Again, Kubernetes operators can be referred to the Kubernetes documentation if it substantively covers the etcd topics. Focus the options in the "What's next?" section to point to a few (two or three) learning paths for specific persona use cases. Remove getting-started instructions from the main GitHub repo README and instead point the user to the documentation. @@ -272,7 +278,7 @@ Move issue and PR submission guidelines from the documentation ("Triage") to the ### Inclusive language -Audit the documentation for non-inclusive language. +Audit the documentation for non-inclusive language. See the [Inclusive Naming Initiative](https://inclusivenaming.org/) website. # Contributor documentation diff --git a/assessments/0010-etcd/etcd-implementation.md b/assessments/0010-etcd/etcd-implementation.md index 9f2144d..320cc59 100644 --- a/assessments/0010-etcd/etcd-implementation.md +++ b/assessments/0010-etcd/etcd-implementation.md @@ -44,12 +44,13 @@ Name the tasks using gerund phrases ("-ing" form, like "Reading ..." and "Writin In an "Overview" or "Start here" page, outline etcd's user roles or personas. These probably include: - *Evaluator*: Someone trying to determine whether etcd is appropriate for their product, project, or organization. -- *Admin or Operator*: Someonereponsible for setting up and maintaining a production etcd service. +- *Admin or Operator*: Someone reponsible for setting up and maintaining a standalone (not installed as the backstore for Kubernetes) production etcd service. +- *Kubernetes Admin*: Someone responsible for installing and maintaining a Kubernetes cluster that uses etcd as the backstore. - *Developer*: Someone incorporating or integrating etcd into an application or service. ## Write installation instructions for Kubernetes -"Installation as part of Kubernetes installation" is missing. Write and test a procedure for this. +"Installation as part of Kubernetes installation" is missing. This is a task for the Kubernetes Admin role. The etcd install page can link to Kubernetes documentation, especially in cases where the Kubernetes installation process automatically includes the etcd install. The etcd documentation should include etcd-specific instructions that aren't included in the Kubernetes doc. If in doubt, duplicating instructions between the two products is preferable to omitting documentation. ## Write Linux installation instructions @@ -57,15 +58,7 @@ Linux installation instructions are missing ("TDB") from the Installation page. ## Update quickstart and new user workflows -Write separate "Getting started" workflows for Developer and Operator users. - -## Write release notes - -Write release notes for each major and minor release going forward. Release notes should include: -- New and changed features -- Known issues -- Updated roadmap information -- Upgrade procedures +Write separate "Getting started" workflows for Developer, Standalone Operator, and Kubernetes Admin users. Again, the Kubernetes Admin documentation can link to coverage in the Kubernetes documentation, but the writer should ensure that major use cases are covered, including adding details in the etcd documentation if necessary. # Reorganize the documentation @@ -80,6 +73,8 @@ Reorganized the documentation to contain the following main elements: - Detailed installation and configuration for each user role (Contents of current "Installation" page) - Developer guide - Operator guide + - Standalone etcd installation + - Kubernetes Admin - Troubleshooting - Reference - Configuration @@ -91,21 +86,26 @@ Reorganized the documentation to contain the following main elements: Following are specific recommendations for each section of the documentation. -**Quickstart**: 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. For the developer path, link to the "Set up a local cluster" page rather than the install page. +**Quickstart**: Rename to "Quick start" (two words). Add a "Prerequisites" section and revise the "What's next" section to focus on three separate paths: +- Development +- Operations +- Kubernetes backstore + +For the developer path, link to the "Set up a local cluster" page rather than the install page. **Demo**: Redundant with Operations guide > Authentication guides > Authentication. Remove from the ToC. -**Tutorials**: Rename "Tasks". Rename each task by removing "How to" and using "-ing" verb form. Make steps in each task explicit; one-step tasks are okay. Organize by user role: Developer, Operator, or both, or put each roles' tasks in the corresponding guide. +**Tutorials**: Rename "Tasks". Rename each task by removing "How to" and using "-ing" verb form. Make steps in each task explicit; one-step tasks are okay. Organize by user role: Developer, Operator, or Kubernetes Admin, or put each roles' tasks in the corresponding guide. **Install**: Rename "Installation" and put each installation on a separate page, collapsible in the ToC. Each should contain Prerequisites, step-by-step instructions, and a "What's next?" section. **FAQ**: Move to near the end of the ToC. Longer explanations in the FAQ might be better as part of conceptual information -- for example, in the system or architecture overview. -**Libraries and tools**: Move to the Reference section. Consider organizing by user role , or labeling each tool or library by user role. Move "Projects using etcd" to a logo wall or at least to its own page on the website. +**Libraries and tools**: Move to the Reference section. Consider organizing by user role, or labeling each tool or library by user role. Move "Projects using etcd" to a logo wall or at least to its own page on the website. **Metrics**: Move to the Operations Guide. -**Reporting bugs**: Combine with the "Triage" topics and move to the repo. Include references to this contributor informationin the Developer and Operations guides. +**Reporting bugs**: Combine with the "Triage" topics and move to the repo. Include references to this contributor information in the Developer and Operations guides. **Tuning**: Move to the Operations Guide. @@ -143,7 +143,7 @@ Following are specific recommendations for each section of the documentation. ***Why gRPC gateway***: Put the introductory material (that describes why you'd want to use gRPC) in the system overview. Present the rest of as its own sub-guide in the Tasks section or as a guide in the Developer Guide. A complete reference to the options should be available in the Reference section. -***gRPC naming and discovery***: This should go (heh) in a Golang-specific part of the Developer guide. +***gRPC naming and discovery***: Combine with the gRPC gateway sub-guide (See Why gRPC gateway). ***etcd features***: Rename "Feature lifecycle" or "Feature maturity". This information might belong in the system overview, but it seems relevant to developers and admins alike. Also, reference this article from the release notes. @@ -151,7 +151,7 @@ Following are specific recommendations for each section of the documentation. ***API reference: concurrency***: Move to Reference section. -**Operations guide**: In general, consider rewriting sections in this guide to be step-by-step tasks; in many cases it's not immediately clear what to do, even if CLI examples are given. +**Operations guide**: Split into guides for two distinct user roles: Operators of standalone etcd installations, and Kubernetes admins using etcd as the Kubernetes backing store. The Kubernetes Admin guide can link to the Kubernetes technical documentation and the standalone Operations guide where necessary; this is usually preferable to duplicating information. The Kubernetes and etcd projects should communicate about how best to document etcd operation in Kubernetes; as far as I can tell this has not been done. In general, consider rewriting sections in this guide to be step-by-step tasks; in many cases it's not immediately clear what to do, even if CLI examples are given. ***Authentication Guides*** @@ -181,7 +181,7 @@ Following are specific recommendations for each section of the documentation. ***Data Corruption***: Move to Troubleshooting section. -**Benchmarks**: Mostly redundant with Benchmark section in Operations guide > Performance. Move any non-redundant info to Performance section in Operations guide. Remove benchmarks of unsupported versions. +**Benchmarks**: Mostly redundant with Benchmark section in Operations guide > Performance. Move any non-redundant info to the Performance section in the Operations guide. Remove benchmarks of unsupported versions. **Upgrading**: Move to the Operations guide. Remove old upgrade paths if they're no longer needed or relevant. @@ -190,6 +190,17 @@ Following are specific recommendations for each section of the documentation. **Triage**: Suggest putting this information for users and contributors in the repo and providing a link from the documentation to create a cleaner separation of product documentation and project documentation. Put the link in the intro to the Troubleshooting section. +## Move release notes + +Consider moving release notes to the documentation (from the code repo) on the basis that they are user, rather than contributor, documentation. + +Release notes should include: +- New and changed features +- Known issues +- Updated roadmap information +- Upgrade procedures + + diff --git a/assessments/0010-etcd/etcd-issues.md b/assessments/0010-etcd/etcd-issues.md index 12f728f..128383e 100644 --- a/assessments/0010-etcd/etcd-issues.md +++ b/assessments/0010-etcd/etcd-issues.md @@ -8,14 +8,14 @@ tags: etcd Here is an outline of the recommended changes to the etcd documentation. Proposed issues to be added to the project repo follow. - Complete and update instructional documentation. - - Describe etcd's user roles (personas). + - Describe etcd's user roles (personas). Split the Operator persona into two: For standalone etcd installations, and for Kubernetes backstore installations. - Convert tutorials to tasks. The "tutorials" as presented in the current doc are actually granular tasks. Document key tasks as procedures rather than tutorials. - - Document Kubernetes and Linux installation procedures. + - Document or link to Kubernetes backstore installation procedures. + - Document Linux installation procedures. - Update and clarify quick start and new user workflows. - Revise the Installation guide. - Make the Developer Guide task-oriented. - Make the Operations Guide task-oriented. - - Going forward, write release notes for each major and minor release. - Reorganize the documentation. - Make instructional documentation (tasks and procedures) easier to find by putting them in their own section (like the tutorials currently are). - Move *project* documentation (documentation for OSS contributors) to the etcd GitHub repo. Move *product* documentation (documentation for those who use the etcd software, in any capacity) to the technical documentation in the website repo. @@ -30,7 +30,8 @@ Here is an outline of the recommended changes to the etcd documentation. Propose 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*: Someonereponsible for setting up and maintaining a production etcd service. +- *Admin or Operator*: Someonereponsible 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. @@ -46,7 +47,7 @@ Rewrite each Tutorial as step-by-step instructions for a single task in an indiv ## Issue: Write installation instructions for Kubernetes -Write the procedure [Installation as part of Kubernetes installation](install/#installation-as-part-of-kubernetes-installation). +Write the procedure [Installation as part of Kubernetes installation](install/#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. ## Issue: Write Linux installation instructions @@ -96,6 +97,8 @@ This information is a duplicate of the [Features](https://github.com/etcd-io/etc 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. + Following are comments on the existing sections within the Operations Guide. ### Issue: Authentication guides > Authentication @@ -145,18 +148,6 @@ Rename to "Versioning policy". Move to the top of the version list. Put a link t 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. -## Issue: Add release notes to new releases - -Add the production of release notes to the major and minor new release process for contributors. - -Release notes should include: -- New and changed features -- Known issues -- Updated roadmap information -- Upgrade procedures -- All release-specific information - - # 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. @@ -223,7 +214,7 @@ Pages to be moved as-is, usually under an organizing heading. Links (listed in t | integrations/ | quickstart/ | Move to the Reference section. Consider organizing by user role , or labeling each tool or library by user role. | | integrations/#projects-using-etcd | quickstart/ | Move to a logo wall or at least to its own page on the website. | | reporting_bugs/ | | Combine with the "Triage" topics and move to the repo's Contributor guide. Link from the Troubleshooting guide. | -| faq/ | | Move to near the end of the ToC. | +| faq/ | | Move to near the end of the ToC. | | dev-guide/api_reference_v3/ | op-guide/runtime-configuration/ | Move to the Reference section. | | dev-guide/api_concurrency_reference_v3/ | | Move to the Reference section. | | op-guide/container/ | | Put in the Clustering Guide. | @@ -232,6 +223,18 @@ Pages to be moved as-is, usually under an organizing heading. Links (listed in t | triage/ | | Move to the repo and provide a link from the documentation (release notes) to create a cleaner separation of product documentation and project documentation. | +## Issue: Move release notes to user documentation + +Move the release notes out of the repo and into to the user documentation. + +Release notes should include: +- New and changed features +- Known issues +- Updated roadmap information +- Upgrade procedures +- All release-specific information + + ## Issue: Consolidate all reference information Consolidate all reference information (APIs and Glossary) to a reference-specific section.