From ea4327e4e38a99590b360f99ee46250c54391d8a Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Wed, 29 Nov 2023 16:46:28 -0800 Subject: [PATCH 01/10] Create 0010-etcd/etcd-analysis.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: dwelsch-esi Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 381 +++++++++++++++++++++++++ 1 file changed, 381 insertions(+) create mode 100644 assessments/0010-etcd/etcd-analysis.md diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md new file mode 100644 index 0000000..f6d31d9 --- /dev/null +++ b/assessments/0010-etcd/etcd-analysis.md @@ -0,0 +1,381 @@ + # etcd CNCF tech docs analysis + +Prepared by: Dave Welsch ([@dwelsch-esi][dwelsch-esi])
+Date: + +## Introduction + +This document assesses the quality and completeness of the [etcd][etcd-io] project's documentation and website. + +This document: + +- Measures existing documentation quality against the CNCF’s standards +- Provides examples of great documentation as a reference +- Recommends a program of key improvements with the largest return on investment +- Provides guidance to making the recommended improvements actionable TBD + + +## How this document works + +The assessment is divided into three sections: + +- **Project documentation:** for end users of the project, aimed at people who intend to use it +- **Contributor documentation:** for new and existing contributors to the project +- **Website:** for branding, website structure, and maintainability + +Each section begins with a rating based on a rubric with appropriate [criteria](criteria.md) for the section. The rubric uses the following scale: + +| Rating | Meaning | +| --- | --- | +| 1 | Is not present | +| 2 | Needs improvement to meet project maturity standards | +| 3 | Meets project maturity standards | +| 4 | Meets or exceeds project maturity standards | +| 5 | Consistently exceeds project maturity standards | + +The assessment also includes a summary of recommendations at the end. + +## Project documentation + +etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. + +| Criterion | Rating (1-5) | +| --- | --- | +| Information architecture | 2 - needs improvement | +| New user content | 3 - meets standards | +| Content maintainability | 3 - meets standards | +| Content creation processes | 2 - needs improvement | +| Inclusive language | 2 - needs improvement | + + +### Comments + +The following sections contain brief assessments of each element of the Project Documentation rubric. + +#### Information architecture + +There is **high-level conceptual** and design content, but it is hidden in a *Learning* section two-thirds of the way down the TOC. + +The *Learning* section, right before *Developer guide* in the ToC, is a catch-all for a lot of different types of information: + +- An architectural overview (actually a fairly detailed explanation of how etcd's client and resiliency architectures work). +- Adoption decision information, in *etcd versus other key-value stores*. +- Also a glossary. + +There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents. + +As far as I can tell, the documentation is **feature complete**. It lacks an adequate introduction and overview. + +There are **instructions** for features. These instructions include: + +- A Quickstart guide +- Installation instructions +- Tutorials +- Instructions on how to tune the server cluster +- Using the CLI + +... and other tasks and procedures. + +There might be **undocumented tasks** associated with key features; a more thorough analysis of key use cases is required to make that determination. + +The **"happy path"** is not a simple procedure, but I believe that there is sufficient documentation of the most common use cases (configure and run HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. + +Task and tutorial content is **clearly named according to user goals**. + +**Escalation paths** are clearly described in [Reporting bugs](https://etcd.io/docs/v3.5/reporting_bugs/) and [Triage](https://etcd.io/docs/v3.5/triage/). + +The product provides a [**reference for the API**](https://etcd.io/docs/v3.5/learning/api/). The documentation also references many language-specific libraries used to integrate with etcd. + +Documentation content is **up to date and is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". + +Examples: + +* https://prometheus.io/docs/introduction/overview/ +* https://kubernetes.io/docs/home/ + + +#### New user content + +There are **install** and **quick start** entries in the ToC. + +The **installation** page gives step-by-step instructions for installing 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". + +There is an example **installation** on the [etcd Play](http://play.etcd.io/install) server. + +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/). + +The *Quickstart* section lists suggested next steps in a *What's next?* heading. However, there is no such section on the *Installation* page, and in neither location is a clear **workflow path** delineated. + +There is no **new user signpost** in the documentation. The closest equivalent is the *Quickstart* section, which has a rudimentary "What's next?" section as previously described. + +The examples in the installation, configuration, and other documentation provide ample code to **copy-paste**. + +Examples: + +* https://falco.org/docs/getting-started/ +* https://prometheus.io/docs/introduction/first_steps/ + + +#### Content maintainability & site mechanics + +Documentation is fully **searchable**. Searches are limited to the stable software version. + +The website content folder contains a **language-specific directory** in its hierarchy, implying a mechanism for doing **internationalization** if necessary. There do not appear to be plans to translate the documentation from English. + +Documentation content is **versioned** with the software. Versions are maintained in separate **directories** in the website content repo. + +Examples: + +* https://kubernetes.io/docs/contribute/ + +#### Content creation processes + +There are instructions for contributing to documentation and for **releasing a new version** of the etcd **documentation** in the `README.md` file in the [website repo](https://github.com/etcd-io/website/blob/main/README.md). The instructions are out of date and seem to require intervention to fix a bad current-version redirect. + +It's not immediately clear **who is responsible** for approving documentation PRs. + +The website has a [**list of maintainers and reviewers**](https://github.com/etcd-io/website/blob/main/MAINTAINERS). + +Examples: + +* https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly documented maintainers) +* https://thanos.io/tip/contributing/how-to-contribute-to-docs.md/ + +#### Inclusive language + +Language is mostly inclusive. For example, the neutral terms "Leader" and "Follower" are used to describe server failover roles. + +However, there are isolated instances of somewhat **non-inclusive language**. For example: + +- [installation check][install-check]: contains "sanity check", a term designated "Strongly Consider Replacing" by the [Inclusive Naming Initiative][inclusive-naming]. +- There is some use of language like "easy", "simple", and "just [take an action]"; for example, "Creating a user is as easy as" in [Role-based access control](https://etcd.io/docs/v3.5/op-guide/authentication/rbac/). + +### Recommendations + +Lose the animated GIFs of CLI interactions. Especially the multi-window ones. They illustrate nothing and make the reader seasick. + + + +## Contributor documentation + +etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. + +| Criterion | Rating (1-5) | +| --- | --- | +| Communication methods documented | 3 - meets standards | +| Beginner friendly issue backlog | 3 - meets standards | +| “New contributor” getting started content | 3 - meets standards | +| Project governance documentation | 4 - meets or exceeds standards | + + +### Comments + +Instructions for building the website state that the local build starts the server on `localhost:8888`. It's actually `localhost:1313` which then starts `8888` Not sure why this is necessary yet. TBD. + +#### Communication methods documented + +**Communication channels** include a Google Group and Twitter, and are documented on the [Community][etcd-community] page. + +There is a link to the **GitHub** repository in the website footer. There are links on the Community page to the [**GitHub** Discussions][etcd-git-discuss] page and the [How to contribute][etcd-howtocontrib]. + +The Community page has a schedule, minutes, and recordings of the project's biweekly **meetings**. + +There does not seem to be any period broadcast communication like a **mailing list**. + +Examples: +https://kubernetes.io/community/ + +#### Beginner friendly issue backlog + +There is a label (`area/documentation`) for **documentation issues**. There is a separate **good first issue** label. Issues are generally **well documented** by submitters and discussed in the Issues forum. + +There are a number of **stale issues**. Here's a summary of the age of open issues for etcd at the time of this writing: + +| Age | Count | Histogram | +| --- | ----- | --- | +| < 1 mo | 16 | *** | +| 1 mo - 2 mo | 9 | ** | +| 2 mo - 3 mo | 15 | *** | +| 3 mo - 6 mo | 35 | ******* | +| 6 mo - 12 mo | 40 | ******** | +| > 12 mo | 54 | *********** | + +Examples: + +* https://github.com/opentracing/opentracing.io/issues (all of open tracing’s backlogs are well maintained!) + + +#### New contributor getting started content + +There is a [**Community**][etcd-community] page on the etcd website. There is no dedicated **"first-contributor"** document, but there are multiple resources and pointers in the general contributor instructions. New users should have minimal difficulty **finding help** if they need it. + +Examples: + +* https://github.com/helm/community +* https://github.com/backstage/community + + +#### Project governance documentation + +[**Project goverance**][etcd-govern] is clearly documented. + +Examples: + +* https://github.com/kubernetes/steering + +### Recommendations + + + +## Website + +etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. + +| Criterion | Rating (1-5) | +| --- | --- | +| Single-source for all files | 4 | +| Meets min website req. (for maturity level) | 2 | +| Usability, accessibility, and design | 3 | +| Branding and design | 4 | +| Case studies/social proof | | +| SEO, Analytics, and site-local search | | +| Maintenance planning | | +| A11y plan & implementation | | +| Mobile-first plan & impl. | | +| HTTPS access & HTTP redirect | | +| Google Analytics 4 for production only | | +| Indexing allowed for production server only | | +| Intra-site / local search | | +| Account custodians are documented | | + +Scale: +| Rating | Meaning | +| --- | --- | +| 1 | Is not present | +| 2 | Is incomplete | +| 3 | Is complete but misplaced, distributed, or obscured | +| 4 | Is complete and meets project maturity standards | +| 5 | Exceeds project maturity standards | + +### Comments + +#### Single-source requirement + +The website has its own GitHub **repository**. The website repo contains the documentation and is separated from the project source code. Contributor documentation is contained mostly in the main *etcd* repo in well labeled Markdown files. + +#### Minimal website requirements + +Except for archived projects, requirements are cumulative through project maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. + +Listed and acknowledged below are the (cumulative) _minimal_ website requirements for projects based on their [maturity level][website-min-reqs]: sandbox, incubating, graduated and archived. + +| Maturity | Requirement | Met? | +| --- | --- | --- | +| Sandbox | Majority of [Website guidelines][website-guidelines] satisfied | Yes | +| Sandbox | [Docs assessment][assess-howto] [submitting a request][cncf-servicedesk] completed. | Yes | +| Sandbox | **Project documentation** exists – somewhere. It is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website. (May still be in the project GitHub repo, for example.) | Yes | +| Incubating | All [Website guidelines][website-guidelines] satisfied | No - no DCO some repos, incl. doc | +| Incubating | Request docs (re-)assessment through CNCF [service desk][cncf-servicedesk] | Yes | +| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | No | +| Incubating | **Project doc**: Hosted directly | Yes | +| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | Yes | +| Graduated | [Docs assessment][assess-howto]: all assessment follow-through actions are complete | | +| Graduated | **Project doc** fully addresses needs of key stakeholders | No | +| Archived | The website repo is in an [archived state][archiving-repo] | n/a | +| Archived | Archived status of the project is obvious to site visitors | n/a | +| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a | + +#### Usability, accessibility and devices + +The site is **usable from mobile**. **Doc pages are readable**. Features such as **search** and **top-nav** work; the **in-page TOC** is missing on a small phone screen. A **mobile-first design** does not make sense for this project. + +Most, but not all **color contrasts** seem significant enough for color-impaired readers. For example, there are some light-blue on dark-blue labels on buttons on the landing page. Basic **website features**, including navigation, can be done via **keyboard**. Unknown whether **text-to-speech** is a good user experience for listeners. + +Examples: + +* https://helm.sh/ + +#### Branding and design + +The website and documentation carry an **easily recognizable brand** for the project based on logo, color scheme, and template layout. The brand is used **consistently** on the site. The text is easily **readable**. + +Examples: + +* https://helm.sh/ + + +#### Case studies/social proof + +The landing page lists a tiny **"logo wall"** of four "Used by" organizations, but does not offer **case studies**. Instead, it links to their home pages. No **user testimonials** are available. + +There is a **project blog**, but it is not a site of active discussion; blog post frequency is annual or less. There do not seem to be any **community talks** available on the website. The YouTube channel contains videos of the bi-weekly meetings. + +Examples: + +* https://www.fluentd.org/testimonials (user testimonials) +* https://goharbor.io/ (logo wall) +* https://blog.rook.io/ (blog) + + +#### SEO, Analytics and site-local search + +***TBD*** + +**Analytics:** +* Is analytics enabled for the production server? +* Is analytics disabled for all other deploys? +* If your project used Google Analytics, have you migrated to GA4? +* Can Page-not-found (404) reports easily be generated from you site analytics? Provide a sample of the site's current top-10 404s. + +**Indexing and Search:** +* Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? +* Is local intra-site search available from the website? + +* Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) + +#### Maintenance planning + +The website uses Hugo and Docsy, which are the preferred **website tooling** for CNCF projects. + +Web maintainers cultivated? ***TBD*** + +Site build times reasonable? ***TBD*** + +Site maintainers have **adequate permissions** to update the website. (I assume. ***TBD***). + + +Examples: + +* http://kubernetes.io + +#### Other + +The website is accessible via **HTTPS**. Requests using **HTTP** are properly redirected to the **HTTPS** URLs. + +### Recommendations + +TBD + +## Recommendations + + + + +[dwelsch-esi]: https://github.com/dwelsch-esi +[install]: https://etcd.io/docs/v3.5/install/ +[0010-etcd]: https://github.com/cncf/techdocs/assessments/0010-etcd.md +[etcd-io]: https://etcd.io +[inclusive-naming]: https://inclusivenaming.org +[install-check]: https://etcd.io/docs/v3.5/install/#installation-check +[website-min-reqs]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[assess-howto]: https://github.com/cncf/techdocs/blob/main/assessments/howto.md +[website-guidelines]: https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md +[cncf-servicedesk]: https://servicedesk.cncf.io +[archiving-repo]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories +[mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first +[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility +[etcd-io]: httpd://etcd.io +[etcd-community]: https://etcd.io/community/ +[etcd-howtocontrib]: https://github.com/etcd-io/etcd/blob/main/CONTRIBUTING.md +[etcd-git-discuss]: https://github.com/etcd-io/etcd/discussions +[etcd-govern]: https://github.com/etcd-io/etcd/blob/main/GOVERNANCE.md From 520ece914479bafa556d2e4280da373b7023f4bb Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Mon, 11 Dec 2023 20:37:40 +0000 Subject: [PATCH 02/10] Updated etcd-analysis.md Signed-off-by: dwelsch-esi Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 183 ++++++++++++------------- 1 file changed, 88 insertions(+), 95 deletions(-) diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index f6d31d9..83fc8bb 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -1,39 +1,75 @@ - # etcd CNCF tech docs analysis + --- +title: etcd Documentation Analysis +tags: etcd +created: 2023-09-01 +modified: 2023-12-08 +author: Dave Welsch (@dwelsch-esi) +--- -Prepared by: Dave Welsch ([@dwelsch-esi][dwelsch-esi])
-Date: +# Introduction -## Introduction +This document analyzes the effectiveness and completeness of the [etcd][etcd-io] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. -This document assesses the quality and completeness of the [etcd][etcd-io] project's documentation and website. +According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. + +## Purpose + +This document was written to analyze the current state of etcd documentation. It aims to provide project leaders with an informed understanding of their project documentation and to outline an actionable plan for improvement. This document: -- Measures existing documentation quality against the CNCF’s standards -- Provides examples of great documentation as a reference +- Analyzes the current etcd technical documentation and website +- Compares existing documentation against the CNCF’s standards - Recommends a program of key improvements with the largest return on investment -- Provides guidance to making the recommended improvements actionable TBD +## Scope of analysis -## How this document works +The documentation discussed here includes the entire contents of the website (which contains the technical docs), as well as documentation for contributors and users on the etcd GitHub repository. -The assessment is divided into three sections: +The etcd website and documentation are written in Markdown and are compiled using the Hugo static site generator with the Docsy theme and served from the Netlify platform. The site's code is stored on the etcd GitHub repo. -- **Project documentation:** for end users of the project, aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project -- **Website:** for branding, website structure, and maintainability +**In scope:** +- Website: https://etcd.io +- Documentation: https://etcd.io/docs +- Website repo: https://github.com/etcd-io/website +- Main project contributor info: https://github.com/etcd-io/etcd -Each section begins with a rating based on a rubric with appropriate [criteria](criteria.md) for the section. The rubric uses the following scale: +**Out of scope:** +- Other etcd repos: https://github.com/etcd-io/* -| Rating | Meaning | -| --- | --- | -| 1 | Is not present | -| 2 | Needs improvement to meet project maturity standards | -| 3 | Meets project maturity standards | -| 4 | Meets or exceeds project maturity standards | -| 5 | Consistently exceeds project maturity standards | -The assessment also includes a summary of recommendations at the end. +## How this document is organized + +This document is divided into three sections that represent three major areas of concern: + +- **Project documentation:** concerns documentation for users of the etcd software, aimed at people who intend to use it +- **Contributor documentation:** concerns documentation for new and existing contributors to the etcd OSS project +- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability + +Each section begins with summary ratings based on a rubric with appropriate [criteria][cncf-doc-criteria] for the section, then proceeds to: +- **Comments**: observations about the existing documentation, with a focus on how it does or does not help etcd users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of the documentation. + +An accompanying document, [etcd-implementation.md][implementation-doc], breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items should be tracked as a series of Github [issues][etcd-issues]. + + +## How to use this document + +Readers interested only in actionable improvements should skip this document and read [etcd-implementation.md][implementation-doc]. + +Readers interested in the current state of the documentation and the reasoning behind the recommendations should read this document or the section pertaining to their area of concern: + +- [Project documentation][proj-doc] +- [Contributor documentation][contributor-doc] +- [Website and documentation infrrastructure][website] + +Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [Criteria][cncf-doc-criteria] specification. + + +### Recommendations, requirements, and best practices + +Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, in most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how apply those best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. + ## Project documentation @@ -42,7 +78,7 @@ etcd is a **graduated** project of CNCF. This means that the project should have | Criterion | Rating (1-5) | | --- | --- | | Information architecture | 2 - needs improvement | -| New user content | 3 - meets standards | +| New user content | 2 - needs improvement | | Content maintainability | 3 - meets standards | | Content creation processes | 2 - needs improvement | | Inclusive language | 2 - needs improvement | @@ -60,13 +96,13 @@ The *Learning* section, right before *Developer guide* in the ToC, is a catch-al - An architectural overview (actually a fairly detailed explanation of how etcd's client and resiliency architectures work). - Adoption decision information, in *etcd versus other key-value stores*. -- Also a glossary. +- A glossary. There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents. -As far as I can tell, the documentation is **feature complete**. It lacks an adequate introduction and overview. +The documentation is not quite **feature complete**. There are a few **undocumented tasks** associated with key features. For example, Kubernetes installation is not fully documented. -There are **instructions** for features. These instructions include: +There are **instructions** for various features. These instructions include: - A Quickstart guide - Installation instructions @@ -76,9 +112,9 @@ There are **instructions** for features. These instructions include: ... and other tasks and procedures. -There might be **undocumented tasks** associated with key features; a more thorough analysis of key use cases is required to make that determination. +The documentation contains an adequate introduction and overview, but these are buried in the doc and difficult to find. -The **"happy path"** is not a simple procedure, but I believe that there is sufficient documentation of the most common use cases (configure and run HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. +The **"happy path"** for etcd is not a simple procedure, but I believe that there is sufficient documentation of the most common use cases (configure and run HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. Task and tutorial content is **clearly named according to user goals**. @@ -88,11 +124,6 @@ The product provides a [**reference for the API**](https://etcd.io/docs/v3.5/lea Documentation content is **up to date and is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". -Examples: - -* https://prometheus.io/docs/introduction/overview/ -* https://kubernetes.io/docs/home/ - #### New user content @@ -110,11 +141,6 @@ There is no **new user signpost** in the documentation. The closest equivalent i The examples in the installation, configuration, and other documentation provide ample code to **copy-paste**. -Examples: - -* https://falco.org/docs/getting-started/ -* https://prometheus.io/docs/introduction/first_steps/ - #### Content maintainability & site mechanics @@ -124,9 +150,6 @@ The website content folder contains a **language-specific directory** in its hie Documentation content is **versioned** with the software. Versions are maintained in separate **directories** in the website content repo. -Examples: - -* https://kubernetes.io/docs/contribute/ #### Content creation processes @@ -136,10 +159,6 @@ It's not immediately clear **who is responsible** for approving documentation PR The website has a [**list of maintainers and reviewers**](https://github.com/etcd-io/website/blob/main/MAINTAINERS). -Examples: - -* https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly documented maintainers) -* https://thanos.io/tip/contributing/how-to-contribute-to-docs.md/ #### Inclusive language @@ -152,8 +171,7 @@ However, there are isolated instances of somewhat **non-inclusive language**. Fo ### Recommendations -Lose the animated GIFs of CLI interactions. Especially the multi-window ones. They illustrate nothing and make the reader seasick. - +I strongly recommend removing the animated GIFs of CLI interactions. Especially the multi-window ones. They illustrate nothing and make the reader seasick. Depending on their purpose, replace them with code samples and/or flow diagrams. ## Contributor documentation @@ -180,10 +198,8 @@ There is a link to the **GitHub** repository in the website footer. There are li The Community page has a schedule, minutes, and recordings of the project's biweekly **meetings**. -There does not seem to be any period broadcast communication like a **mailing list**. +There does not seem to be any periodic broadcast communication like a **mailing list**. -Examples: -https://kubernetes.io/community/ #### Beginner friendly issue backlog @@ -191,41 +207,30 @@ There is a label (`area/documentation`) for **documentation issues**. There is a There are a number of **stale issues**. Here's a summary of the age of open issues for etcd at the time of this writing: + | Age | Count | Histogram | | --- | ----- | --- | -| < 1 mo | 16 | *** | -| 1 mo - 2 mo | 9 | ** | -| 2 mo - 3 mo | 15 | *** | -| 3 mo - 6 mo | 35 | ******* | +| < 1 mo | 22 | **** | +| 1 mo - 2 mo | 10 | ** | +| 2 mo - 3 mo | 10 | ** | +| 3 mo - 6 mo | 38 | ******* | | 6 mo - 12 mo | 40 | ******** | -| > 12 mo | 54 | *********** | - -Examples: - -* https://github.com/opentracing/opentracing.io/issues (all of open tracing’s backlogs are well maintained!) +| > 12 mo | 52 | *********** | #### New contributor getting started content -There is a [**Community**][etcd-community] page on the etcd website. There is no dedicated **"first-contributor"** document, but there are multiple resources and pointers in the general contributor instructions. New users should have minimal difficulty **finding help** if they need it. - -Examples: - -* https://github.com/helm/community -* https://github.com/backstage/community +There is a [**Community**][etcd-community] page on the etcd website. There is no dedicated **"first-contributor"** document, but there are multiple resources and pointers in the general contributor instructions. New contributors should have minimal difficulty **finding help** if they need it. #### Project governance documentation [**Project goverance**][etcd-govern] is clearly documented. -Examples: - -* https://github.com/kubernetes/steering ### Recommendations - +Create and expose a conspicuous "First contributor start here" document, with links to the other contributor resources. ## Website @@ -237,16 +242,16 @@ etcd is a **graduated** project of CNCF. This means that the project should have | Meets min website req. (for maturity level) | 2 | | Usability, accessibility, and design | 3 | | Branding and design | 4 | -| Case studies/social proof | | +| Case studies/social proof | 3 | | SEO, Analytics, and site-local search | | | Maintenance planning | | | A11y plan & implementation | | -| Mobile-first plan & impl. | | -| HTTPS access & HTTP redirect | | +| Mobile-first plan & impl. | 3 | +| HTTPS access & HTTP redirect | 4 | | Google Analytics 4 for production only | | | Indexing allowed for production server only | | | Intra-site / local search | | -| Account custodians are documented | | +| Account custodians are documented | 4 | Scale: | Rating | Meaning | @@ -291,18 +296,11 @@ The site is **usable from mobile**. **Doc pages are readable**. Features such as Most, but not all **color contrasts** seem significant enough for color-impaired readers. For example, there are some light-blue on dark-blue labels on buttons on the landing page. Basic **website features**, including navigation, can be done via **keyboard**. Unknown whether **text-to-speech** is a good user experience for listeners. -Examples: - -* https://helm.sh/ #### Branding and design The website and documentation carry an **easily recognizable brand** for the project based on logo, color scheme, and template layout. The brand is used **consistently** on the site. The text is easily **readable**. -Examples: - -* https://helm.sh/ - #### Case studies/social proof @@ -310,11 +308,7 @@ The landing page lists a tiny **"logo wall"** of four "Used by" organizations, b There is a **project blog**, but it is not a site of active discussion; blog post frequency is annual or less. There do not seem to be any **community talks** available on the website. The YouTube channel contains videos of the bi-weekly meetings. -Examples: - -* https://www.fluentd.org/testimonials (user testimonials) -* https://goharbor.io/ (logo wall) -* https://blog.rook.io/ (blog) +There is an ADOPTERS.md file in the etcd-io/etcd repository that lists a number of production users of etcd. Each entry in the file gives some details about the production installation, including when it was launched, the cluster size, what application is using etcd, and the cloud environment. The list of production users in this file is probably not exhaustive. #### SEO, Analytics and site-local search @@ -337,16 +331,14 @@ Examples: The website uses Hugo and Docsy, which are the preferred **website tooling** for CNCF projects. + Web maintainers cultivated? ***TBD*** Site build times reasonable? ***TBD*** Site maintainers have **adequate permissions** to update the website. (I assume. ***TBD***). - -Examples: - -* http://kubernetes.io +Maintainers of the etcd-io/website repository are adequately documented in the OWNERS file in the repo. Approvers and reviewers are listed. #### Other @@ -361,10 +353,14 @@ TBD -[dwelsch-esi]: https://github.com/dwelsch-esi -[install]: https://etcd.io/docs/v3.5/install/ -[0010-etcd]: https://github.com/cncf/techdocs/assessments/0010-etcd.md [etcd-io]: https://etcd.io +[cncf-doc-criteria]: ../criteria.md +[implementation-doc]: ./etcd-implementation.md +[proj-doc]: ../criteria.md#project-documentation +[contributor-doc]: ../criteria.md/#contributor-documentation +[website]: ../criteria.md/#website +[etcd-issues]: ./etcd-issues.md +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 [inclusive-naming]: https://inclusivenaming.org [install-check]: https://etcd.io/docs/v3.5/install/#installation-check [website-min-reqs]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations @@ -372,9 +368,6 @@ TBD [website-guidelines]: https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md [cncf-servicedesk]: https://servicedesk.cncf.io [archiving-repo]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories -[mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first -[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility -[etcd-io]: httpd://etcd.io [etcd-community]: https://etcd.io/community/ [etcd-howtocontrib]: https://github.com/etcd-io/etcd/blob/main/CONTRIBUTING.md [etcd-git-discuss]: https://github.com/etcd-io/etcd/discussions From a8d9ae2e56fefb378836f605758a72565af091e3 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Thu, 21 Dec 2023 19:27:54 +0000 Subject: [PATCH 03/10] In progress Signed-off-by: dwelsch-esi Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 15 +- assessments/0010-etcd/etcd-implementation.md | 197 +++++++++++++++++++ 2 files changed, 207 insertions(+), 5 deletions(-) create mode 100644 assessments/0010-etcd/etcd-implementation.md diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index 83fc8bb..bb2fa46 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -33,6 +33,7 @@ The etcd website and documentation are written in Markdown and are compiled usin - Documentation: https://etcd.io/docs - Website repo: https://github.com/etcd-io/website - Main project contributor info: https://github.com/etcd-io/etcd +- Demo server: http://play.etcd.io **Out of scope:** - Other etcd repos: https://github.com/etcd-io/* @@ -98,8 +99,6 @@ The *Learning* section, right before *Developer guide* in the ToC, is a catch-al - Adoption decision information, in *etcd versus other key-value stores*. - A glossary. -There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents. - The documentation is not quite **feature complete**. There are a few **undocumented tasks** associated with key features. For example, Kubernetes installation is not fully documented. There are **instructions** for various features. These instructions include: @@ -114,7 +113,7 @@ There are **instructions** for various features. These instructions include: The documentation contains an adequate introduction and overview, but these are buried in the doc and difficult to find. -The **"happy path"** for etcd is not a simple procedure, but I believe that there is sufficient documentation of the most common use cases (configure and run HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. +The **"happy path"** for etcd is not a simple procedure, but I believe that there is sufficient documentation of the most common use cases (configure and run HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. Exception: There is a "TBD" under "Installation as part of Kubernetes installation". Task and tutorial content is **clearly named according to user goals**. @@ -124,10 +123,13 @@ The product provides a [**reference for the API**](https://etcd.io/docs/v3.5/lea Documentation content is **up to date and is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". +The [demo-server][demo-server] has an *install* menu item that goes to "an example workflow to install and deploy etcd." However, the page consists of a form containing parameters (with no explanation of each parameter other than the label) followed by a CLI script that varies depending on the installation type you choose. Presumably you're supposed to run the script to do the install, but there are no clear task instructions at all. Novice users will have a hard time with this. #### New user content -There are **install** and **quick start** entries in the ToC. +There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents. Better would be if it went to an overview page with "what to do next" options. + +There are **install** and **quick start** entries in the technical documentation ToC. The **installation** page gives step-by-step instructions for installing 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". @@ -144,7 +146,7 @@ The examples in the installation, configuration, and other documentation provide #### Content maintainability & site mechanics -Documentation is fully **searchable**. Searches are limited to the stable software version. +Documentation is fully **searchable**. Searches are limited to the current (stable) software version. Search also returns blog entries. The website content folder contains a **language-specific directory** in its hierarchy, implying a mechanism for doing **internationalization** if necessary. There do not appear to be plans to translate the documentation from English. @@ -344,6 +346,8 @@ Maintainers of the etcd-io/website repository are adequately documented in the O The website is accessible via **HTTPS**. Requests using **HTTP** are properly redirected to the **HTTPS** URLs. +The [demo server][demo-server] uses unsecured HTTP. + ### Recommendations TBD @@ -372,3 +376,4 @@ TBD [etcd-howtocontrib]: https://github.com/etcd-io/etcd/blob/main/CONTRIBUTING.md [etcd-git-discuss]: https://github.com/etcd-io/etcd/discussions [etcd-govern]: https://github.com/etcd-io/etcd/blob/main/GOVERNANCE.md +[demo-server]: http://play.etcd.io diff --git a/assessments/0010-etcd/etcd-implementation.md b/assessments/0010-etcd/etcd-implementation.md new file mode 100644 index 0000000..9a83b1c --- /dev/null +++ b/assessments/0010-etcd/etcd-implementation.md @@ -0,0 +1,197 @@ +--- +title: Implementing etcd Doc Improvements +tags: etcd +--- + +# Introduction + +This document provides actionable suggestions for improving the etcd technical documentaiton. + +For an analysis and general discussion of recommendations on etcd technical documentation, see [etcd-analysis.md][etcd-analysis]. + +## Recommendations, requirements, and best practices + +Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, in most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how apply those best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. + +The top-level documentation recommendations for this project are: + +- Complete documentation for important use cases, such as Kubernetes installation. +- Rename the "Learning" section to something more descriptive such as "Technical Overview", and move reference information (APIs and Glossary) to a reference-specific page. +- Reorganize the documentation to make instructional documentation easier to find. + + +# Implementation: Complete documentation for important use cases + +We recommend that the project audit the documentation to ensure that instructions exist for all tasks required for mainstream use cases. This includes "getting started" tasks such as installation, configuration, and server tuning; maintenance tasks such as cluster reconfiguration and upgrades and dependency management; product use, including configuration with popular products; and development, especially integrating key storage and retrieval with new products using existing APIs. For example, "Installation as part of Kubernetes installation" is entirely missing ("TBD–Help wanted") on the Installation page. + + +## Administrator + +The following artifacts should be written and made findable for administrators. + +1. A server installation and setup guide for administrators. Provide clear, step-by-step instructions for downloading and deploying etcd to an organization. + + Instructions can also be provided for installing a local, group-level, or test deployment, but these instructions should be separate and clearly labeled as non-production. + +1. An Administrator Guide, with instructions on how to do such things as: + - Start and stop the etcd server + - Install and configure etcd plugins + - Manage the many software dependencies for etcd and its plugins + - Maintain the etcd database + - Upgrade and downgrade the etcd release verison + - Troubleshoot common problems + - Tune server performance + +## Developer + +The following artifacts should be written and made findable for developers. + +1. A getting started guide for developers. Provide a clear work path that describes how to: + 1. Downloead and install any necessary software components + 1. Integrate etcd with an existing development environment + +1. A User Guide for developers. Provide clear instructions for these tasks: + - Adding an existing product to etcd + - Creating a new product in etcd + - Updating a product in etcd + - Documenting a product in etcd + - Deprecating and retiring a product from etcd + - Searching for a component in etcd + + +## Integrator + +There are a dizzying array of issues with writing, modifying, and maintaining plugins in etcd. This is not a detailed recipe for documenting those issues. For integrators, at a high level, a program should be undertaken to: + +1. Organize integrator tasks from most basic and common (write a simple plugin; decide between backend and frontend plugin) to more complex (integrate with external systems; use a proxy; implement authentication). +2. Where possible, using the exisitng documentation as a starting point, write step-by-step procedures for discrete integration tasks (starting with how to write a basic plugin). +3. Organize existing reference and conceptual information (such as API references and architecture discussions) into supporting documentation, referenced from the integration tasks. + + +## Contributor + +For a plugin-dependent project like etcd, it's vital that community members contribute plugins, for two reasons: + +1. To expand the base functionality of etcd by covering common use cases +2. To provide complete examples of how plugins are structured, written, and added to the project + +Contributor documentation should be in Markdown files in the etcd GitHub repo and should be limited to how to contribute software to the product. "How to write a plugin" documentation should be included in the website-based doc as described above. + +# Organize and "signpost" documentation + +Right now different types of documentation (conceptual/architectural; instructional; reference) for different user roles are intermixed throughout the documentation site. + +Below is a proposed organization for Backspace by user role, based on a fairly typical documentation set for developer-oriented software. Using exactly this organization is not important. What is important, again, is to document use cases, broken down into tasks, by user role. The documentation should reflect the needs of each user role and be organized such that any user has a clear path to learning the software and becoming proficient as quickly as possible. + +Some documents are used by more than one user role. These docs are listed first under the heading **Common**. + +## Common + +| Document | Description | +| --- | --- | +| Technical overview | A discussion of what the product is and what problems it solves. Ideally, the discussion starts with a summary and provides explanations of increasing depth to address different audiences (evaluator -> developer -> contributor, e.g.). | +| Release notes | Release-specific information, including: new features; performance improvements; bugs and known issues; deprecated features; software dependency changes; and experimental or beta features. | +| Glossary | A dictionary of product-specific terms. Also commonly includes domain- and industry-specific terms that are necessary to understanding the product. | +| Knowledge base | An encyclopedic collection of related background, conceptual, and reference information that doesn't fit elsewhere in the documentation. Similar to a FAQ, but more structured, more searchable and, therefore, more useful. | + + +## Evaluator + +| Document | Description | +| --- | --- | +| Logo wall | Not a technical document, but a *de rigeur* feature on a product website these days. The logo wall shows at a glance an instantly recognizable selection of organizations that use the product. The logos typically link to testimonials or to the organizations' own websites. | +| Case studies | Another element on a product website that is as much marketing as technical material, a case study nonetheless helps an evaluator decide whether to adopt the product. A handful of well written case studies is sufficient. | + +## Administrator + +| Document | Description | +| --- | --- | +| CLI reference | An indexed reference to the command-line interface. The etcd CLI does a wide variety of tasks and is used both the administrator and by developers. | +| Installation and configuration guide | A guide to downloading, installing, and configuring an organization-wide etcd instance ("app"). | +| Administrator guide | Contains all tasks the administrator needs to maintain the etcd app: onboarding developers; installing plugins; starting, stopping, upgrading, and troubleshooting the app; using containers; evaluating and tuning server performance. | + + +## Developer + +| Document | Description | +| --- | --- | +| Getting started guide | A document that usually walks a developer through setting up a development environment (for a language or API). In the case of etcd, this is more of an integration with their existing environment. Nonetheless, this should explain how to configure all the tools the developer needs to begin using etcd. | +| Developer guide | Contains all tasks that the developer needs to use the etcd app under normal circumstances: adding products ("catalog population"), modifying, and searching for products; writing documentation; using templates. | +| CLI reference | An indexed reference to the command-line interface. The etcd CLI does a wide variety of tasks and is used both the administrator and by developers. | +| Tutorials | Tasks that are good candidates for tutorials are difficult, often-used tasks that must be mastered to use the product effectively. Many of these are probably in daily use by developers. | +| Cookbooks | There might be specialized tasks required of developers by an organization that should be documented, especially if they are performed infrequently. | + + +## Integrator + +| Document | Description | +| --- | --- | +| Technical overview | Same as the common technical overview, but an integrator will need more detail about the plugin architecture. | +| Cookbooks | The integrator will need to write plugins. This encompasses a large body of task knowledge. The best way to document these is as a collection of tasks or procedures explaining how to complete each task. Even with a comprehensive collection of task documents, some creativity is probably needed by the integrator, since every new plugin by definition is solving a new problem. | + + +## Contributor + +| Document | Description | +| --- | --- | +| GitHub Instructions | Contributing a plugin to etcd is essentially an exercise in creating and shepherding a pull request through the etcd community process. This can be documented entirely in GitHub, or it can be a separate section in the etcd documentation. Regardless, the contributing instructional material should be separate from the integration/"How to write a plugin" material. | + + +# Website and documentation infrastructure + + +## Single-source repo + +Move the etcd documentation out of the [etcd repo][etcd-github-project] and into its own repo within the [etcd project][etcd-etcd]. Write explicit instructions for contributing to documentation and place them in the repo README. + +In the meantime, put references to the documentation contributing and build instructions alongside the project code instructions in the contributor documentation in the etcd repo. + + +## Case studies/social proof + +Implement a **logo wall** of participating organizations, with links to testimonials or the organizations' websites. Write or solicit a handful of representative case studies and link them from the website. + + + +## SEO, Analytics and site-local search + +Add documentation and website custodians to the project maintainer lists in `OWNERS.md` and wherever else project maintainers are documented. + + +## Maintenance planning + +Add a prominent call for website and documentation maintainers in the project introduction alongside the call for code maintainers. + + +## Accessibility + +Improve compliance in these areas: +- **Images** should have alternative text. +- **Links** should have discernible text. + + + + +[etcd-analysis]: ./etcd-analysis.md +[etcd-etcd]: https://github.com/etcd-io/etcd +[etcd-github-project]: https://github.com/etcd-io +[user-roles]: #user-roles + +[etcd-io]: https://etcd.io +[cncf-doc-criteria]: ../criteria.md +[proj-doc]: ../criteria.md#project-documentation +[contributor-doc]: ../criteria.md/#contributor-documentation +[website]: ../criteria.md/#website +[etcd-issues]: ./etcd-issues.md +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 +[inclusive-naming]: https://inclusivenaming.org +[install-check]: https://etcd.io/docs/v3.5/install/#installation-check +[website-min-reqs]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[assess-howto]: https://github.com/cncf/techdocs/blob/main/assessments/howto.md +[website-guidelines]: https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md +[cncf-servicedesk]: https://servicedesk.cncf.io +[archiving-repo]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories +[etcd-community]: https://etcd.io/community/ +[etcd-howtocontrib]: https://github.com/etcd-io/etcd/blob/main/CONTRIBUTING.md +[etcd-git-discuss]: https://github.com/etcd-io/etcd/discussions +[etcd-govern]: https://github.com/etcd-io/etcd/blob/main/GOVERNANCE.md From cbc02c047c3bc820b3e09700aa9eeb67767eaf1d Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Tue, 2 Jan 2024 22:34:03 +0000 Subject: [PATCH 04/10] Updates to analysis document. Signed-off-by: dwelsch-esi Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 27 +++++++++++--------- assessments/0010-etcd/etcd-implementation.md | 4 +-- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index bb2fa46..e74f4cd 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -2,7 +2,7 @@ title: etcd Documentation Analysis tags: etcd created: 2023-09-01 -modified: 2023-12-08 +modified: 2024-01-02 author: Dave Welsch (@dwelsch-esi) --- @@ -74,7 +74,7 @@ Notwithstanding the fact that this analysis measures documentation against CNCF ## Project documentation -etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. +etcd is a **graduated** project of CNCF. This means that the project should have [*very high*][cncf-doc-criteria] standards for documentation. | Criterion | Rating (1-5) | | --- | --- | @@ -95,8 +95,9 @@ There is **high-level conceptual** and design content, but it is hidden in a *Le The *Learning* section, right before *Developer guide* in the ToC, is a catch-all for a lot of different types of information: -- An architectural overview (actually a fairly detailed explanation of how etcd's client and resiliency architectures work). -- Adoption decision information, in *etcd versus other key-value stores*. +- An architectural overview (explanations of how etcd's client and resiliency architectures work). +- Adoption decision information, in *etcd versus other key-value stores*. This information needs updating. +- An overview of the gRPC-based API. - A glossary. The documentation is not quite **feature complete**. There are a few **undocumented tasks** associated with key features. For example, Kubernetes installation is not fully documented. @@ -111,11 +112,13 @@ There are **instructions** for various features. These instructions include: ... and other tasks and procedures. -The documentation contains an adequate introduction and overview, but these are buried in the doc and difficult to find. +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. For example, "What's next?" at the end of the Quickstart instructions provides too many unrelated choices. The **"happy path"** for etcd is not a simple procedure, but I believe that there is sufficient documentation of the most common use cases (configure and run HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. Exception: There is a "TBD" under "Installation as part of Kubernetes installation". -Task and tutorial content is **clearly named according to user goals**. +Task and tutorial content is **clearly named according to user goals**. + +Tutorials have animated graphics of command line activity that adds nothing of value to the explanation and is very distracting. Replace with a listing of the output if necessary, but remove the animation. **Escalation paths** are clearly described in [Reporting bugs](https://etcd.io/docs/v3.5/reporting_bugs/) and [Triage](https://etcd.io/docs/v3.5/triage/). @@ -123,7 +126,7 @@ The product provides a [**reference for the API**](https://etcd.io/docs/v3.5/lea Documentation content is **up to date and is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". -The [demo-server][demo-server] has an *install* menu item that goes to "an example workflow to install and deploy etcd." However, the page consists of a form containing parameters (with no explanation of each parameter other than the label) followed by a CLI script that varies depending on the installation type you choose. Presumably you're supposed to run the script to do the install, but there are no clear task instructions at all. Novice users will have a hard time with this. +The [demo-server][demo-server] has an *install* menu item that goes to "an example workflow to install and deploy etcd." However, the page consists of a form containing parameters (with no explanation of each parameter other than the label) followed by a CLI script that varies depending on the installation type you choose. Presumably you're supposed to run the script to do the install, but there are no clear task instructions at all. Novice users will have a hard time with this. Also, why is this information on the demo server at all? Users should be referred to an installation procedure in the documentationa. #### New user content @@ -133,7 +136,7 @@ There are **install** and **quick start** entries in the technical documentation The **installation** page gives step-by-step instructions for installing 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". -There is an example **installation** on the [etcd Play](http://play.etcd.io/install) server. +There is an example **installation** on the [etcd Play](http://play.etcd.io/install) server. It's not clear how this is useful. 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/). @@ -146,7 +149,7 @@ The examples in the installation, configuration, and other documentation provide #### Content maintainability & site mechanics -Documentation is fully **searchable**. Searches are limited to the current (stable) software version. Search also returns blog entries. +Documentation is fully **searchable**. Searches are apparently limited to the current (stable) software version, though searching for "upgrade" lists instructions for upgrading 3.3 -> 3.4 in the v3.4 doc, 3.2 -> 3.3 in the 3.3 doc, and so on. Search also returns blog entries. The website content folder contains a **language-specific directory** in its hierarchy, implying a mechanism for doing **internationalization** if necessary. There do not appear to be plans to translate the documentation from English. @@ -155,11 +158,11 @@ Documentation content is **versioned** with the software. Versions are maintaine #### Content creation processes -There are instructions for contributing to documentation and for **releasing a new version** of the etcd **documentation** in the `README.md` file in the [website repo](https://github.com/etcd-io/website/blob/main/README.md). The instructions are out of date and seem to require intervention to fix a bad current-version redirect. +There are instructions for contributing to documentation and for **releasing a new version** of the etcd **documentation** in the `README.md` file in the [website repo](https://github.com/etcd-io/website/blob/main/README.md). The instructions are out of date. See issues #383, 405, 406, 459. + -It's not immediately clear **who is responsible** for approving documentation PRs. -The website has a [**list of maintainers and reviewers**](https://github.com/etcd-io/website/blob/main/MAINTAINERS). +The website has a [**list of maintainers and reviewers**](https://github.com/etcd-io/website/blob/main/OWNERS). Those maintainer **responsible for approving** documentation PRs are listed as "approvers". This list might need to be updated. #### Inclusive language diff --git a/assessments/0010-etcd/etcd-implementation.md b/assessments/0010-etcd/etcd-implementation.md index 9a83b1c..aefcd53 100644 --- a/assessments/0010-etcd/etcd-implementation.md +++ b/assessments/0010-etcd/etcd-implementation.md @@ -16,8 +16,8 @@ Notwithstanding the fact that this analysis measures documentation against CNCF The top-level documentation recommendations for this project are: - Complete documentation for important use cases, such as Kubernetes installation. -- Rename the "Learning" section to something more descriptive such as "Technical Overview", and move reference information (APIs and Glossary) to a reference-specific page. -- Reorganize the documentation to make instructional documentation easier to find. +- Rename the "Learning" section to something more descriptive such as "Technical Overview", and move reference information (APIs and Glossary) to a reference-specific section. +- Reorganize the documentation to make instructional documentation (tasks and procedures) easier to find. # Implementation: Complete documentation for important use cases From 27c804e35c6a5183b623b8af7073659fcca0172f Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Fri, 5 Jan 2024 22:05:37 +0000 Subject: [PATCH 05/10] Updates to analysis and implementation docs. Signed-off-by: dwelsch-esi Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 308 ++++++++++++++----- assessments/0010-etcd/etcd-implementation.md | 207 ++++++------- 2 files changed, 330 insertions(+), 185 deletions(-) diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index e74f4cd..786801e 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -69,10 +69,10 @@ Examples of CNCF documentation that demonstrate the analysis criteria are linked ### Recommendations, requirements, and best practices -Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, in most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how apply those best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. +Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, in most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how apply documentation best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. -## Project documentation +# Project documentation etcd is a **graduated** project of CNCF. This means that the project should have [*very high*][cncf-doc-criteria] standards for documentation. @@ -85,11 +85,13 @@ etcd is a **graduated** project of CNCF. This means that the project should have | Inclusive language | 2 - needs improvement | -### Comments +## Comments + +Much of the documentation seems as if it hasn't been reviewed and updated for a while. The following sections contain brief assessments of each element of the Project Documentation rubric. -#### Information architecture +### Information architecture There is **high-level conceptual** and design content, but it is hidden in a *Learning* section two-thirds of the way down the TOC. @@ -100,72 +102,86 @@ The *Learning* section, right before *Developer guide* in the ToC, is a catch-al - An overview of the gRPC-based API. - A glossary. -The documentation is not quite **feature complete**. There are a few **undocumented tasks** associated with key features. For example, Kubernetes installation is not fully documented. +The documentation is not **feature complete**. There are some **undocumented tasks** associated with key features. For example, Kubernetes and Linux installations is not fully documented. The [Authentication][docs-authentication] page is a stub containing only a CLI example. -There are **instructions** for various features. These instructions include: +The documentation contains **instructions** for various features. These instructions include: - A Quickstart guide - Installation instructions - Tutorials -- Instructions on how to tune the server cluster +- How to tune the server cluster - Using the CLI ... and other tasks and procedures. 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. For example, "What's next?" at the end of the Quickstart instructions provides too many unrelated choices. -The **"happy path"** for etcd is not a simple procedure, but I believe that there is sufficient documentation of the most common use cases (configure and run HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. Exception: There is a "TBD" under "Installation as part of Kubernetes installation". +The **"happy path"** for etcd is not a simple procedure, but 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. -Task and tutorial content is **clearly named according to user goals**. +Task and tutorial content are **clearly named according to user goals**. However, using "-ing" verb forms instead of "How to ..." would make headings easier to navigate. -Tutorials have animated graphics of command line activity that adds nothing of value to the explanation and is very distracting. Replace with a listing of the output if necessary, but remove the animation. +Tutorials have animated graphics of command line activity. -**Escalation paths** are clearly described in [Reporting bugs](https://etcd.io/docs/v3.5/reporting_bugs/) and [Triage](https://etcd.io/docs/v3.5/triage/). +**Escalation paths** are clearly described in [Reporting bugs](https://etcd.io/docs/v3.5/reporting_bugs/) and [Triage][etcdio-triage]. The product provides a [**reference for the API**](https://etcd.io/docs/v3.5/learning/api/). The documentation also references many language-specific libraries used to integrate with etcd. -Documentation content is **up to date and is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". +Documentation content is **up to date and is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". The site lists several versions of the documentation for down-level releases. These could be archived. + +There are references to previous releases in the documentation. Most of these should probably be removed. -The [demo-server][demo-server] has an *install* menu item that goes to "an example workflow to install and deploy etcd." However, the page consists of a form containing parameters (with no explanation of each parameter other than the label) followed by a CLI script that varies depending on the installation type you choose. Presumably you're supposed to run the script to do the install, but there are no clear task instructions at all. Novice users will have a hard time with this. Also, why is this information on the demo server at all? Users should be referred to an installation procedure in the documentationa. +Benchmarks for down-level versions are available in the current documentation. It's not clear why these old benchmarks haven't been removed from the documentation. -#### New user content +There is an example **installation** on the [etcd Play](http://play.etcd.io/install) server that prsents "an example workflow to install and deploy etcd." This page consists of a form containing parameters (with no explanation of each parameter other than the label) followed by a CLI script that varies depending on the installation type you choose. Presumably you're supposed to run the script to do the install, but there are no clear task instructions at all. It's not clear how this is useful. Novice users will have a hard time with this. Also, why is this information on the demo server at all? Users should be referred to an installation procedure in the documentation. If this represents a separate, automated installation workflow it should be offered as a procedure in the user doc. -There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents. Better would be if it went to an overview page with "what to do next" options. +### New user content -There are **install** and **quick start** entries in the technical documentation ToC. +There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents. Better would be if it went to an overview page that laid out learning paths for different users ("Start here"). -The **installation** page gives step-by-step instructions for installing 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". +There are **install** and **quick start** entries in the technical documentation ToC. These are good starting points but could be refined. -There is an example **installation** on the [etcd Play](http://play.etcd.io/install) server. It's not clear how this is useful. +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. 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/). The *Quickstart* section lists suggested next steps in a *What's next?* heading. However, there is no such section on the *Installation* page, and in neither location is a clear **workflow path** delineated. -There is no **new user signpost** in the documentation. The closest equivalent is the *Quickstart* section, which has a rudimentary "What's next?" section as previously described. +There is no **new user signpost** in the documentation. The closest equivalent is the *Quickstart* section, but the Quickstart does not differentiate among user roles (Developer? Operator? Trying to decide whether to adopt?). The examples in the installation, configuration, and other documentation provide ample code to **copy-paste**. +There are instructions for installing and getting started in the etcd-io/etcd [README][etcd-readme]. It would be preferable to point new users and contributors to the documentation straightaway. + -#### Content maintainability & site mechanics +### Content maintainability & site mechanics + +Documentation content is **versioned** with the software. Versions are maintained in separate **directories** in the website content repo. Documentation is fully **searchable**. Searches are apparently limited to the current (stable) software version, though searching for "upgrade" lists instructions for upgrading 3.3 -> 3.4 in the v3.4 doc, 3.2 -> 3.3 in the 3.3 doc, and so on. Search also returns blog entries. -The website content folder contains a **language-specific directory** in its hierarchy, implying a mechanism for doing **internationalization** if necessary. There do not appear to be plans to translate the documentation from English. +There are links to docs for previous versions in some of the 3.5 documentation files: -Documentation content is **versioned** with the software. Versions are maintained in separate **directories** in the website content repo. +- dev-internal/discovery_protocol.md +- op-guide/runtime-configuration.md +- op-guide/recovery.md +- metrics.md +- dev-guide/discovery_protocol.md + +The website content folder contains a **language-specific directory** in its hierarchy, implying a mechanism for doing **internationalization** if necessary. There do not appear to be plans to translate the documentation from English. +There is a Github issue label (`area/documentation`) for **documentation issues**. -#### Content creation processes -There are instructions for contributing to documentation and for **releasing a new version** of the etcd **documentation** in the `README.md` file in the [website repo](https://github.com/etcd-io/website/blob/main/README.md). The instructions are out of date. See issues #383, 405, 406, 459. +### Content creation processes +There are instructions for contributing to documentation and for **releasing a new version** of the etcd **documentation** in the `README.md` file in the [website repo](https://github.com/etcd-io/website/blob/main/README.md). The instructions are out of date. See issues #383, 405, 406. +The website has a [**list of maintainers and reviewers**](https://github.com/etcd-io/website/blob/main/OWNERS). Those maintainer **responsible for approving** documentation PRs are listed as "approvers". -The website has a [**list of maintainers and reviewers**](https://github.com/etcd-io/website/blob/main/OWNERS). Those maintainer **responsible for approving** documentation PRs are listed as "approvers". This list might need to be updated. +The website repo [README](../../README.md) is out of date. For example, instructions for building the website state that the local build starts the server on `localhost:8888`. It's actually `localhost:1313`. -#### Inclusive language +### Inclusive language Language is mostly inclusive. For example, the neutral terms "Leader" and "Follower" are used to describe server failover roles. @@ -174,12 +190,92 @@ However, there are isolated instances of somewhat **non-inclusive language**. Fo - [installation check][install-check]: contains "sanity check", a term designated "Strongly Consider Replacing" by the [Inclusive Naming Initiative][inclusive-naming]. - There is some use of language like "easy", "simple", and "just [take an action]"; for example, "Creating a user is as easy as" in [Role-based access control](https://etcd.io/docs/v3.5/op-guide/authentication/rbac/). -### Recommendations +## Recommendations + +### Information architecture + +Reorganize the table of contents (ToC) to separate three types of information: +- **Conceptual**: Information that is necessary to understanding but not directly usable. The main bodies of conceptual information are architecture and system overviews. +- **Instructional**: How to complete tasks necessary to use the software (this includes programming and integration using APIs). Organize instructional material by user role: for etcd, the two main user roles are 1) developers, and 2) operators or admins responsible for running and maintaining etcd server instances. +- **Reference**: The details of CLI commands, API metehods and objects, system configuration options, and other information that needs to be looked up in the course of performning a task. + +For an excellent and very literal example of this approach, see the [Kubernetes documentation][k8s-doc]. + +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. + +Use "-ing" verb forms instead of "How to ..." as headings for procedures. + +Break procedures out to one per page. For example, instead of every installation case being on one page, create a navigation page explaining the use case for each installation and link to a page whose sole content is step-by-step installation instructions. + +Replace animated GIFs of command line activity with static listings of the outputs that can be studied at normal reading speed. + +Create a Troubleshooting page that helps with common problems. Link to Slack channels and issue and PR submission instructions in the GitHub repo in case more help is needed. + +Consider archiving old versions of the documentation to reduce clutter. + +Remove references to previous releases in the documentation. These references are in the following 3.5 documentation files: + +- learning/design-learner.md +- learning/design-client.md +- op-guide/versioning.md +- op-guide/container.md +- op-guide/clustering.md +- op-guide/authentication/rbac.md +- op-guide/maintenance.md +- benchmarks/* +- upgrades/* +- dev-guide/api_grpc_gateway.md +- dev-guide/interacting_v3.md +- dev-guide/grpc_naming.md + +In general, confine release-specific discussion to the Release Notes. -I strongly recommend removing the animated GIFs of CLI interactions. Especially the multi-window ones. They illustrate nothing and make the reader seasick. Depending on their purpose, replace them with code samples and/or flow diagrams. +Remove benchmarks for down-level versions in the current documentation if they're no longer relevant. +Consider removing the installation example from the [etcd Play](http://play.etcd.io/install) server and pointing the user to the documentation. -## Contributor documentation +### New user content + +Point "Learn more" links to a Start Here page that provides orientation and sets out paths for different user roles. For example, the Developer path should provide instructions for: + +1. Installing a local server. +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. + +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. + +Remove getting-started instructions from the main GitHub repo README and instead point the user to the documentation. + +### Content maintainability & site mechanics + +Remove links to documentation for previous versions from current documentation version. Going forward, write doc for each release without referring to previous ("In 3.2 this feature was changed ...") or future ("We plan to upgrade this in the next release ..."). Such comments should go only in release notes. + +References to previous versions are in the following 3.5 documentation files: + +- dev-internal/discovery_protocol.md +- op-guide/runtime-configuration.md +- op-guide/recovery.md +- metrics.md +- dev-guide/discovery_protocol.md + + +### Content creation processes + +Update the content creation instructions in the website README file. + +Move issue and PR submission guidelines from the documentation ("Triage") to the Github repo. Link to these guidelines from a Troubleshooting section in the docs. + + +### Inclusive language + +Audit the documentation for non-inclusive language. + + +# Contributor documentation etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. @@ -191,11 +287,9 @@ etcd is a **graduated** project of CNCF. This means that the project should have | Project governance documentation | 4 - meets or exceeds standards | -### Comments +## Comments -Instructions for building the website state that the local build starts the server on `localhost:8888`. It's actually `localhost:1313` which then starts `8888` Not sure why this is necessary yet. TBD. - -#### Communication methods documented +### Communication methods documented **Communication channels** include a Google Group and Twitter, and are documented on the [Community][etcd-community] page. @@ -205,12 +299,14 @@ The Community page has a schedule, minutes, and recordings of the project's biwe There does not seem to be any periodic broadcast communication like a **mailing list**. +[Triage][etcdio-triage] contains instructions for dealing with issues and PRs in the etcd repo. These should be in the repo itself, with a pointer from the documentation at most. + -#### Beginner friendly issue backlog +### Beginner friendly issue backlog -There is a label (`area/documentation`) for **documentation issues**. There is a separate **good first issue** label. Issues are generally **well documented** by submitters and discussed in the Issues forum. +There is a **good first issue** label. Issues are generally **well documented** by submitters and discussed in the Issues forum. There is a label (`area/documentation`) for **documentation issues**. -There are a number of **stale issues**. Here's a summary of the age of open issues for etcd at the time of this writing: +There are a number of **stale issues**. Here's a summary of the age of open issues for the etcd main repo at the time of this writing: | Age | Count | Histogram | @@ -223,57 +319,70 @@ There are a number of **stale issues**. Here's a summary of the age of open issu | > 12 mo | 52 | *********** | -#### New contributor getting started content +### New contributor getting started content There is a [**Community**][etcd-community] page on the etcd website. There is no dedicated **"first-contributor"** document, but there are multiple resources and pointers in the general contributor instructions. New contributors should have minimal difficulty **finding help** if they need it. -#### Project governance documentation +### Project governance documentation [**Project goverance**][etcd-govern] is clearly documented. -### Recommendations +## Recommendations + + +### Communication methods documented -Create and expose a conspicuous "First contributor start here" document, with links to the other contributor resources. +Movethe information from the [Triage][etcdio-triage] doc section into the repo itself, with pointers from the documentation Developer and Operations guides. -## Website + +### Beginner friendly issue backlog + +No recommendations. + + +### New contributor getting started content + +Consider creating a conspicuous "First contributor start here" document in the repo, with links to the other contributor resources. + + +### Project governance documentation + +No recommnendations. + + +# Website etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. | Criterion | Rating (1-5) | | --- | --- | -| Single-source for all files | 4 | -| Meets min website req. (for maturity level) | 2 | -| Usability, accessibility, and design | 3 | -| Branding and design | 4 | -| Case studies/social proof | 3 | +| Single-source for all files | 5 - exemplary | +| Meets min website req. (for maturity level) | 2 - needs improvement | +| Usability, accessibility, and design | 3 - meets standards | +| Branding and design | 4 - meets or exceeds standards | +| Case studies/social proof | 3 - meets standards | | SEO, Analytics, and site-local search | | | Maintenance planning | | | A11y plan & implementation | | -| Mobile-first plan & impl. | 3 | -| HTTPS access & HTTP redirect | 4 | +| Mobile-first plan & impl. | 3 - meets standards | +| HTTPS access & HTTP redirect | 4 - meets or exceeds standards | | Google Analytics 4 for production only | | | Indexing allowed for production server only | | | Intra-site / local search | | -| Account custodians are documented | 4 | +| Account custodians are documented | 4 - meets or exceeds standards | + -Scale: -| Rating | Meaning | -| --- | --- | -| 1 | Is not present | -| 2 | Is incomplete | -| 3 | Is complete but misplaced, distributed, or obscured | -| 4 | Is complete and meets project maturity standards | -| 5 | Exceeds project maturity standards | +## Comments -### Comments +### Single-source requirement -#### Single-source requirement +The website has its own GitHub **repository**. The website repo contains the documentation and is separated from the project source code. -The website has its own GitHub **repository**. The website repo contains the documentation and is separated from the project source code. Contributor documentation is contained mostly in the main *etcd* repo in well labeled Markdown files. +**Contributor documentation** is contained in the [main code repo][github-etcd-etcd] in well labeled Markdown files. -#### Minimal website requirements +### Minimal website requirements Except for archived projects, requirements are cumulative through project maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. @@ -295,28 +404,28 @@ Listed and acknowledged below are the (cumulative) _minimal_ website requirement | Archived | Archived status of the project is obvious to site visitors | n/a | | Archived | Link to successor project website and/or migration documentation (if it exists) | n/a | -#### Usability, accessibility and devices +### Usability, accessibility and devices The site is **usable from mobile**. **Doc pages are readable**. Features such as **search** and **top-nav** work; the **in-page TOC** is missing on a small phone screen. A **mobile-first design** does not make sense for this project. Most, but not all **color contrasts** seem significant enough for color-impaired readers. For example, there are some light-blue on dark-blue labels on buttons on the landing page. Basic **website features**, including navigation, can be done via **keyboard**. Unknown whether **text-to-speech** is a good user experience for listeners. -#### Branding and design +### Branding and design The website and documentation carry an **easily recognizable brand** for the project based on logo, color scheme, and template layout. The brand is used **consistently** on the site. The text is easily **readable**. -#### Case studies/social proof +### Case studies/social proof -The landing page lists a tiny **"logo wall"** of four "Used by" organizations, but does not offer **case studies**. Instead, it links to their home pages. No **user testimonials** are available. +The landing page lists a tiny **"logo wall"** of four "Used by" organizations, though given that one of those organizations is Kubernetes, this seems adequate. The site does not offer **case studies**. Instead, logos link to the organizations' home pages. No **user testimonials** are available. There is a **project blog**, but it is not a site of active discussion; blog post frequency is annual or less. There do not seem to be any **community talks** available on the website. The YouTube channel contains videos of the bi-weekly meetings. There is an ADOPTERS.md file in the etcd-io/etcd repository that lists a number of production users of etcd. Each entry in the file gives some details about the production installation, including when it was launched, the cluster size, what application is using etcd, and the cloud environment. The list of production users in this file is probably not exhaustive. -#### SEO, Analytics and site-local search +### SEO, Analytics and site-local search ***TBD*** @@ -332,9 +441,9 @@ There is an ADOPTERS.md file in the etcd-io/etcd repository that lists a number * Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) -#### Maintenance planning +### Maintenance planning -The website uses Hugo and Docsy, which are the preferred **website tooling** for CNCF projects. +The website uses Hugo and Docsy, which are the recommended **website tooling** for CNCF projects. Web maintainers cultivated? ***TBD*** @@ -345,17 +454,66 @@ Site maintainers have **adequate permissions** to update the website. (I assume. Maintainers of the etcd-io/website repository are adequately documented in the OWNERS file in the repo. Approvers and reviewers are listed. -#### Other +### Other The website is accessible via **HTTPS**. Requests using **HTTP** are properly redirected to the **HTTPS** URLs. The [demo server][demo-server] uses unsecured HTTP. -### Recommendations +## Recommendations -TBD -## Recommendations + + + + + +### Single-source requirement + +No recommendations. + +### Minimal website requirements + +Update website to include DCO or other source validation. + +Identify stakeholders (user roles). Ensure that instructions exist in the documentation for all major use cases for each stakeholder. + + +### Usability, accessibility and devices + +Consider replaciing low-contrast text for the benefit of visually impaired users. + + +### Branding and design + +No recommendations. + + +### Case studies/social proof + +Consider adding user testimonials and/or case studies to the web page. + +Consider posting updates and news to the blog more regularly. + + +### SEO, Analytics and site-local search + +***TBD*** + + +### Maintenance planning + +Consider authorizing contributors to update the website and documentation. + +***TBD*** + + +### Other + +Consider securing the [demo server][demo-server] using HTTPS. + + +# Recommendations @@ -380,3 +538,9 @@ TBD [etcd-git-discuss]: https://github.com/etcd-io/etcd/discussions [etcd-govern]: https://github.com/etcd-io/etcd/blob/main/GOVERNANCE.md [demo-server]: http://play.etcd.io +[github-etcd-etcd]: https://github.com/etcd-io/etcd +[etcdio-triage]: https://etcd.io/docs/v3.5/triage/ +[doc-optimalclustersize-23]: https://etcd.io/docs/v2.3/admin_guide#optimal-cluster-size +[docs-authentication]: https://etcd.io/docs/v3.5/op-guide/authentication/authentication/ +[etcd-readme]: https://github.com/etcd-io/etcd/blob/main/README.md +[k8s-doc]: https://kubernetes.io/docs/home/ diff --git a/assessments/0010-etcd/etcd-implementation.md b/assessments/0010-etcd/etcd-implementation.md index aefcd53..6a40dd9 100644 --- a/assessments/0010-etcd/etcd-implementation.md +++ b/assessments/0010-etcd/etcd-implementation.md @@ -15,183 +15,164 @@ Notwithstanding the fact that this analysis measures documentation against CNCF The top-level documentation recommendations for this project are: -- Complete documentation for important use cases, such as Kubernetes installation. -- Rename the "Learning" section to something more descriptive such as "Technical Overview", and move reference information (APIs and Glossary) to a reference-specific section. -- Reorganize the documentation to make instructional documentation (tasks and procedures) easier to find. +- Complete and update instructional documentation for important use cases: + - Describe etcd's user roles (personas). + - Audit the documentation to ensure important use cases are covered. + - Document Kubernetes and Linux installation procedures. + - Update and clarify quick start and new user workflows. + - Document important tasks as procedures rather than tutorials. + - Clarify which user roles (personas) each task is for. +- Reorganize the documentation. + - Make instructional documentation (tasks and procedures) easier to find by putting them in their own section (like the tutorials currently are). Rename the "Tutorials" section to "Tasks". The tutorials in the current doc are actually granular tasks. + - Rename the "Learning" section to something more descriptive such as "Technical Overview", and move it near the top of the table of contents. + - Consolidate all reference information (APIs and Glossary) to a reference-specific section. + - Remove information about old software revisions from the current version's docs if it's not necessary for a significant segment of users. This includes upgrade procedures and performance benchmarks. -# Implementation: Complete documentation for important use cases +# Implementation: Complete and update documentation for important use cases -We recommend that the project audit the documentation to ensure that instructions exist for all tasks required for mainstream use cases. This includes "getting started" tasks such as installation, configuration, and server tuning; maintenance tasks such as cluster reconfiguration and upgrades and dependency management; product use, including configuration with popular products; and development, especially integrating key storage and retrieval with new products using existing APIs. For example, "Installation as part of Kubernetes installation" is entirely missing ("TBD–Help wanted") on the Installation page. +Ensure that task-based documentation is complete and accurate. Common tasks should be described step-by-step in individual descriptions, each with the goal of walking the user through completion of the task. This is distinct from tutorials, which are designed to teach the user how to accomplish a more complex use case. +Currently, the "Tutorials" section in the documentation contains tasks that should be documented as such. For example, the [How to access etcd][access-tutorial] tutorial should be two separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on the CLI". -## Administrator +Name the tasks using gerund phrases ("-ing" form, like "Reading ..." and "Writing ..."). Eliminate "How to", which clutters the heading with a redundant phrase that the user must skip over. -The following artifacts should be written and made findable for administrators. +## Audit task-based documentation -1. A server installation and setup guide for administrators. Provide clear, step-by-step instructions for downloading and deploying etcd to an organization. +We recommend that the project audit the documentation to ensure that instructions exist for all tasks required for mainstream use cases. This includes "getting started" tasks such as installation, configuration, and server tuning; maintenance tasks such as cluster reconfiguration and upgrades and dependency management; product use, including configuration with popular products; and development, especially integrating key storage and retrieval with new products using existing APIs. - Instructions can also be provided for installing a local, group-level, or test deployment, but these instructions should be separate and clearly labeled as non-production. +## Write installation instructions for Kubernetes -1. An Administrator Guide, with instructions on how to do such things as: - - Start and stop the etcd server - - Install and configure etcd plugins - - Manage the many software dependencies for etcd and its plugins - - Maintain the etcd database - - Upgrade and downgrade the etcd release verison - - Troubleshoot common problems - - Tune server performance +"Installation as part of Kubernetes installation" is entirely missing ("TBD–Help wanted") on the Installation page. -## Developer +## Write Linux installation instructions -The following artifacts should be written and made findable for developers. +Linux installation instructions are missing ("TDB") from the Installation page. -1. A getting started guide for developers. Provide a clear work path that describes how to: - 1. Downloead and install any necessary software components - 1. Integrate etcd with an existing development environment +## Update quickstart and new user workflows -1. A User Guide for developers. Provide clear instructions for these tasks: - - Adding an existing product to etcd - - Creating a new product in etcd - - Updating a product in etcd - - Documenting a product in etcd - - Deprecating and retiring a product from etcd - - Searching for a component in etcd -## Integrator -There are a dizzying array of issues with writing, modifying, and maintaining plugins in etcd. This is not a detailed recipe for documenting those issues. For integrators, at a high level, a program should be undertaken to: +# Reorganize the documentation -1. Organize integrator tasks from most basic and common (write a simple plugin; decide between backend and frontend plugin) to more complex (integrate with external systems; use a proxy; implement authentication). -2. Where possible, using the exisitng documentation as a starting point, write step-by-step procedures for discrete integration tasks (starting with how to write a basic plugin). -3. Organize existing reference and conceptual information (such as API references and architecture discussions) into supporting documentation, referenced from the integration tasks. +Here are specific recommendations for each section of the documentation. While these are only suggestions, if implemented they will bring the site more in line with documentation best practices. -## Contributor +**Quickstart**: Leave here. 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. -For a plugin-dependent project like etcd, it's vital that community members contribute plugins, for two reasons: +**Demo**: Redundant with Operations guide > Authentication guides > Authentication. Remove from the ToC. -1. To expand the base functionality of etcd by covering common use cases -2. To provide complete examples of how plugins are structured, written, and added to the project +**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. -Contributor documentation should be in Markdown files in the etcd GitHub repo and should be limited to how to contribute software to the product. "How to write a plugin" documentation should be included in the website-based doc as described above. +**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. Consider moving to the Operations guide. -# Organize and "signpost" documentation +**FAQ**: Move to near the end of the ToC. Longer explanations in the FAQ might be better as part of conceptual information in the system or architecture overview, for example. -Right now different types of documentation (conceptual/architectural; instructional; reference) for different user roles are intermixed throughout the documentation site. +**Libraries and tools**: Move to the Reference section. Consider labeling each tool or library for what user role will find it useful. -Below is a proposed organization for Backspace by user role, based on a fairly typical documentation set for developer-oriented software. Using exactly this organization is not important. What is important, again, is to document use cases, broken down into tasks, by user role. The documentation should reflect the needs of each user role and be organized such that any user has a clear path to learning the software and becoming proficient as quickly as possible. +**Metrics**: Move to the Operations Guide. -Some documents are used by more than one user role. These docs are listed first under the heading **Common**. +**Reporting bugs**: Combine with the "Triage" topics and move to the repo. Include references to this contributor informationin the Developer and Operations guides. -## Common +**Tuning**: Move to the Operations Guide. -| Document | Description | -| --- | --- | -| Technical overview | A discussion of what the product is and what problems it solves. Ideally, the discussion starts with a summary and provides explanations of increasing depth to address different audiences (evaluator -> developer -> contributor, e.g.). | -| Release notes | Release-specific information, including: new features; performance improvements; bugs and known issues; deprecated features; software dependency changes; and experimental or beta features. | -| Glossary | A dictionary of product-specific terms. Also commonly includes domain- and industry-specific terms that are necessary to understanding the product. | -| Knowledge base | An encyclopedic collection of related background, conceptual, and reference information that doesn't fit elsewhere in the documentation. Similar to a FAQ, but more structured, more searchable and, therefore, more useful. | +**Discovery service protocol**: This page is duplicated in the Developer Guide; see the note there. Remove it from here. +**Logging conventions**: Move to the Operations Guide. -## Evaluator +**Golang modules**: Remove from the ToC. Include this information in the architecture overview. -| Document | Description | -| --- | --- | -| Logo wall | Not a technical document, but a *de rigeur* feature on a product website these days. The logo wall shows at a glance an instantly recognizable selection of organizations that use the product. The logos typically link to testimonials or to the organizations' own websites. | -| Case studies | Another element on a product website that is as much marketing as technical material, a case study nonetheless helps an evaluator decide whether to adopt the product. A handful of well written case studies is sufficient. | +**Learning**: Rename/revamp as "System Overview" or "Architecture Overview" and include sections that explain the conceptual underpinnings of etcd. Move to earlier in ToC, perhaps before "Installation". Recommendations for existing subsections follow. -## Administrator +***Data model***: Include in architecture overview. -| Document | Description | -| --- | --- | -| CLI reference | An indexed reference to the command-line interface. The etcd CLI does a wide variety of tasks and is used both the administrator and by developers. | -| Installation and configuration guide | A guide to downloading, installing, and configuring an organization-wide etcd instance ("app"). | -| Administrator guide | Contains all tasks the administrator needs to maintain the etcd app: onboarding developers; installing plugins; starting, stopping, upgrading, and troubleshooting the app; using containers; evaluating and tuning server performance. | +***etcd client design***: Include in architecture overview. +***etcd learner design***: Include in architecture overview. -## Developer +***etcd v3 authentication design***: Include in architecture overview. -| Document | Description | -| --- | --- | -| Getting started guide | A document that usually walks a developer through setting up a development environment (for a language or API). In the case of etcd, this is more of an integration with their existing environment. Nonetheless, this should explain how to configure all the tools the developer needs to begin using etcd. | -| Developer guide | Contains all tasks that the developer needs to use the etcd app under normal circumstances: adding products ("catalog population"), modifying, and searching for products; writing documentation; using templates. | -| CLI reference | An indexed reference to the command-line interface. The etcd CLI does a wide variety of tasks and is used both the administrator and by developers. | -| Tutorials | Tasks that are good candidates for tutorials are difficult, often-used tasks that must be mastered to use the product effectively. Many of these are probably in daily use by developers. | -| Cookbooks | There might be specialized tasks required of developers by an organization that should be documented, especially if they are performed infrequently. | +***etcd API***: Include in architecture overview. +***KV API guarantees***: Include in architecture overview. -## Integrator +***etcd versus other key-value stores***: I think this properly belongs on the webpage as an evaluation tool. Also, it needs to be updated. -| Document | Description | -| --- | --- | -| Technical overview | Same as the common technical overview, but an integrator will need more detail about the plugin architecture. | -| Cookbooks | The integrator will need to write plugins. This encompasses a large body of task knowledge. The best way to document these is as a collection of tasks or procedures explaining how to complete each task. Even with a comprehensive collection of task documents, some creativity is probably needed by the integrator, since every new plugin by definition is solving a new problem. | +***Glossary***: Move to Reference section. +**Developer guide**: This should contain instructional content (tasks, procedures, tutorials) for developers looking to use etcd in an application. Since there are such a large number of APIs and supported interfaces, it might be wise to think about organizing this information by language, at least partially. -## Contributor +***Discovery service protocol***: What is the use case for this information? If it's to enable a developer to programmatically discover a cluster, leave it here. It might also belong in the Operations guide (but link to the same page, don't copy it), perhaps in the Clustering Guide. -| Document | Description | -| --- | --- | -| GitHub Instructions | Contributing a plugin to etcd is essentially an exercise in creating and shepherding a pull request through the etcd community process. This can be documented entirely in GitHub, or it can be a separate section in the etcd documentation. Regardless, the contributing instructional material should be separate from the integration/"How to write a plugin" material. | +***Set up a local cluster***: Make this the first section in the Developer guide. +***Interacting with etcd***: This page is largely redundant with the Tutorials. Make each task its own page, and consolidate with Tasks as described in "Tutorials" above. -# Website and documentation infrastructure +***Why gRPC gateway***: Put the introductory material (that actually 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. -## Single-source repo +***System limits*** -Move the etcd documentation out of the [etcd repo][etcd-github-project] and into its own repo within the [etcd project][etcd-etcd]. Write explicit instructions for contributing to documentation and place them in the repo README. +***etcd features*** -In the meantime, put references to the documentation contributing and build instructions alongside the project code instructions in the contributor documentation in the etcd repo. +***API reference***: Move to Reference section. +***API reference: concurrency***: Move to Reference section. -## Case studies/social proof +**Operations guide**: Any subsection not listed below doesn't need work. In general, though, 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. -Implement a **logo wall** of participating organizations, with links to testimonials or the organizations' websites. Write or solicit a handful of representative case studies and link them from the website. +***Authentication Guides*** +***Authentication***: Incomplete. +***Configuration options***: Move to Reference section. -## SEO, Analytics and site-local search +***Transport security model***: Rename to "Setting up transport layer security". -Add documentation and website custodians to the project maintainer lists in `OWNERS.md` and wherever else project maintainers are documented. +***Clustering Guide***: Consider breaking up into one page per procedure. +***Run etcd clusters inside containers***: Put in the Clustering Guide. -## Maintenance planning +***Failure modes***: Conceptual information. Consider moving to the architecture overview. What to actually do in case of a failure should be in a Troubleshooting section, like for example the following "Disaster recovery" section. -Add a prominent call for website and documentation maintainers in the project introduction alongside the call for code maintainers. +***Disaster recovery***: Consolidate with other troubleshooting procedures. +***etcd gateway*** -## Accessibility +***gRPC proxy*** + +***Hardware recommendations***: System prerequisite. Move to somewhere before the Cluster Installation section; maybe even put it in a Prereq heading in that section. + +***Maintenance***: Maybe provide a more specific title like "Storage maintenance". + +***Monitoring etcd*** + +***Performance*** + +***Design of runtime reconfiguration***: Move to architecture overview. + +***Runtime reconfiguration*** + +***Supported platforms***: Combine with Hardware recommendations in a System Prerequisites section. + +***Versioning***: Rename to "Versioning policy". Add a documentation versioning policy. Move to top of version list. Put a link to this version policy in every release notes. + +***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. + +**Upgrading**: Move to the Operations guide. Remove old upgrade paths if they're no longer needed or relevant. + +***Upgrading etcd clusters and applications***: As far as I can tell, this page just lists the upbrade pages and isn't needed. + +**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. -Improve compliance in these areas: -- **Images** should have alternative text. -- **Links** should have discernible text. [etcd-analysis]: ./etcd-analysis.md -[etcd-etcd]: https://github.com/etcd-io/etcd -[etcd-github-project]: https://github.com/etcd-io -[user-roles]: #user-roles - -[etcd-io]: https://etcd.io -[cncf-doc-criteria]: ../criteria.md -[proj-doc]: ../criteria.md#project-documentation -[contributor-doc]: ../criteria.md/#contributor-documentation -[website]: ../criteria.md/#website -[etcd-issues]: ./etcd-issues.md [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 -[inclusive-naming]: https://inclusivenaming.org -[install-check]: https://etcd.io/docs/v3.5/install/#installation-check -[website-min-reqs]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations -[assess-howto]: https://github.com/cncf/techdocs/blob/main/assessments/howto.md -[website-guidelines]: https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md -[cncf-servicedesk]: https://servicedesk.cncf.io -[archiving-repo]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories -[etcd-community]: https://etcd.io/community/ -[etcd-howtocontrib]: https://github.com/etcd-io/etcd/blob/main/CONTRIBUTING.md -[etcd-git-discuss]: https://github.com/etcd-io/etcd/discussions -[etcd-govern]: https://github.com/etcd-io/etcd/blob/main/GOVERNANCE.md +[access-tutorial]: https://etcd.io/docs/v3.5/tutorials/how-to-access-etcd/ From fd301a0cf76cb01081f053d24d5115dc98958ee9 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Tue, 9 Jan 2024 00:45:03 +0000 Subject: [PATCH 06/10] Completed first draft of analysis and implementation. Signed-off-by: dwelsch-esi Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 50 ++++++++++++-------------- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index 786801e..59cbe2c 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -2,7 +2,7 @@ title: etcd Documentation Analysis tags: etcd created: 2023-09-01 -modified: 2024-01-02 +modified: 2024-01-08 author: Dave Welsch (@dwelsch-esi) --- @@ -58,7 +58,7 @@ An accompanying document, [etcd-implementation.md][implementation-doc], breaks t Readers interested only in actionable improvements should skip this document and read [etcd-implementation.md][implementation-doc]. -Readers interested in the current state of the documentation and the reasoning behind the recommendations should read this document or the section pertaining to their area of concern: +Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: - [Project documentation][proj-doc] - [Contributor documentation][contributor-doc] @@ -93,7 +93,7 @@ The following sections contain brief assessments of each element of the Project ### Information architecture -There is **high-level conceptual** and design content, but it is hidden in a *Learning* section two-thirds of the way down the TOC. +There is **high-level conceptual** and design content, but it is hard to find. Most of it is in a *Learning* section, which is not a conventional label for a system overview. The *Learning* section, right before *Developer guide* in the ToC, is a catch-all for a lot of different types of information: @@ -114,19 +114,19 @@ The documentation contains **instructions** for various features. These instruct ... and other tasks and procedures. -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. For example, "What's next?" at the end of the Quickstart instructions provides too many unrelated choices. +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 toy server vs. an admin setting up a production server. -The **"happy path"** for etcd is not a simple procedure, but 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. -Task and tutorial content are **clearly named according to user goals**. However, using "-ing" verb forms instead of "How to ..." would make headings easier to navigate. +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. -Tutorials have animated graphics of command line activity. +Tutorials contain large animated graphics of command line activity. Theser are distracting and degrade the usability of the instructions. **Escalation paths** are clearly described in [Reporting bugs](https://etcd.io/docs/v3.5/reporting_bugs/) and [Triage][etcdio-triage]. The product provides a [**reference for the API**](https://etcd.io/docs/v3.5/learning/api/). The documentation also references many language-specific libraries used to integrate with etcd. -Documentation content is **up to date and is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". The site lists several versions of the documentation for down-level releases. These could be archived. +Documentation content **is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". The site lists several versions of the documentation for down-level releases. These could be archived. There are references to previous releases in the documentation. Most of these should probably be removed. @@ -138,7 +138,7 @@ There is an example **installation** on the [etcd Play](http://play.etcd.io/inst There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents. Better would be if it went to an overview page that laid out learning paths for different users ("Start here"). -There are **install** and **quick start** entries in the technical documentation ToC. These are good starting points but could be refined. +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. @@ -159,7 +159,7 @@ Documentation content is **versioned** with the software. Versions are maintaine Documentation is fully **searchable**. Searches are apparently limited to the current (stable) software version, though searching for "upgrade" lists instructions for upgrading 3.3 -> 3.4 in the v3.4 doc, 3.2 -> 3.3 in the 3.3 doc, and so on. Search also returns blog entries. -There are links to docs for previous versions in some of the 3.5 documentation files: +There are links to docs for previous releases in some of the 3.5 documentation files: - dev-internal/discovery_protocol.md - op-guide/runtime-configuration.md @@ -196,7 +196,7 @@ However, there are isolated instances of somewhat **non-inclusive language**. Fo Reorganize the table of contents (ToC) to separate three types of information: - **Conceptual**: Information that is necessary to understanding but not directly usable. The main bodies of conceptual information are architecture and system overviews. -- **Instructional**: How to complete tasks necessary to use the software (this includes programming and integration using APIs). Organize instructional material by user role: for etcd, the two main user roles are 1) developers, and 2) operators or admins responsible for running and maintaining etcd server instances. +- **Instructional**: How to complete tasks necessary to use the software (this includes programming and integration using APIs). Organize instructional material by user role: for etcd, the two main user roles seem to be 1) developers, and 2) operators or admins responsible for running and maintaining etcd server instances. - **Reference**: The details of CLI commands, API metehods and objects, system configuration options, and other information that needs to be looked up in the course of performning a task. For an excellent and very literal example of this approach, see the [Kubernetes documentation][k8s-doc]. @@ -209,7 +209,7 @@ Use "-ing" verb forms instead of "How to ..." as headings for procedures. Break procedures out to one per page. For example, instead of every installation case being on one page, create a navigation page explaining the use case for each installation and link to a page whose sole content is step-by-step installation instructions. -Replace animated GIFs of command line activity with static listings of the outputs that can be studied at normal reading speed. +Replace animated GIFs of command line activity with static listings of the outputs that can be studied and copy/pasted. Create a Troubleshooting page that helps with common problems. Link to Slack channels and issue and PR submission instructions in the GitHub repo in case more help is needed. @@ -234,11 +234,11 @@ In general, confine release-specific discussion to the Release Notes. Remove benchmarks for down-level versions in the current documentation if they're no longer relevant. -Consider removing the installation example from the [etcd Play](http://play.etcd.io/install) server and pointing the user to the documentation. +Consider removing the installation example from the [etcd Play](http://play.etcd.io/install) server and pointing the user to the documentation's installation instructions. ### New user content -Point "Learn more" links to a Start Here page that provides orientation and sets out paths for different user roles. For example, the Developer path should provide instructions for: +Point "Learn more" links to a "Start here" page that provides orientation and sets out paths for different user roles. For example, the Developer path should provide instructions for: 1. Installing a local server. 2. Setting up an environment and testing the server using the CLI. @@ -252,7 +252,7 @@ Remove getting-started instructions from the main GitHub repo README and instead ### Content maintainability & site mechanics -Remove links to documentation for previous versions from current documentation version. Going forward, write doc for each release without referring to previous ("In 3.2 this feature was changed ...") or future ("We plan to upgrade this in the next release ..."). Such comments should go only in release notes. +Remove links to documentation for previous releases from the current documentation version. Going forward, write doc for each release without referring to previous ("In 3.2 this feature was changed ...") or future ("We plan to upgrade this in the next release ..."). Such comments should go only in release notes. References to previous versions are in the following 3.5 documentation files: @@ -277,7 +277,7 @@ Audit the documentation for non-inclusive language. # Contributor documentation -etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. +etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for contributor documentation. | Criterion | Rating (1-5) | | --- | --- | @@ -299,7 +299,7 @@ The Community page has a schedule, minutes, and recordings of the project's biwe There does not seem to be any periodic broadcast communication like a **mailing list**. -[Triage][etcdio-triage] contains instructions for dealing with issues and PRs in the etcd repo. These should be in the repo itself, with a pointer from the documentation at most. +[Triage][etcdio-triage] contains instructions for dealing with issues and PRs in the etcd repo. These should be in the repo itself, with a pointer from the documentation troubleshooting section. ### Beginner friendly issue backlog @@ -334,7 +334,7 @@ There is a [**Community**][etcd-community] page on the etcd website. There is no ### Communication methods documented -Movethe information from the [Triage][etcdio-triage] doc section into the repo itself, with pointers from the documentation Developer and Operations guides. +Move the information from the [Triage][etcdio-triage] doc section into the repo itself, with pointers from the documentation Troubleshooting guide. ### Beginner friendly issue backlog @@ -398,7 +398,7 @@ Listed and acknowledged below are the (cumulative) _minimal_ website requirement | Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | No | | Incubating | **Project doc**: Hosted directly | Yes | | Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | Yes | -| Graduated | [Docs assessment][assess-howto]: all assessment follow-through actions are complete | | +| Graduated | [Docs assessment][assess-howto]: all assessment follow-through actions are complete | No | | Graduated | **Project doc** fully addresses needs of key stakeholders | No | | Archived | The website repo is in an [archived state][archiving-repo] | n/a | | Archived | Archived status of the project is obvious to site visitors | n/a | @@ -448,11 +448,11 @@ The website uses Hugo and Docsy, which are the recommended **website tooling** f Web maintainers cultivated? ***TBD*** -Site build times reasonable? ***TBD*** +The website builds in **reasonable time** on a desktop computer. Site maintainers have **adequate permissions** to update the website. (I assume. ***TBD***). -Maintainers of the etcd-io/website repository are adequately documented in the OWNERS file in the repo. Approvers and reviewers are listed. +Maintainers of the [website repository][website-repo] are adequately documented in the OWNERS file in the repo. Approvers and reviewers are listed. ### Other @@ -463,11 +463,6 @@ The [demo server][demo-server] uses unsecured HTTP. ## Recommendations - - - - - ### Single-source requirement No recommendations. @@ -513,8 +508,6 @@ Consider authorizing contributors to update the website and documentation. Consider securing the [demo server][demo-server] using HTTPS. -# Recommendations - @@ -544,3 +537,4 @@ Consider securing the [demo server][demo-server] using HTTPS. [docs-authentication]: https://etcd.io/docs/v3.5/op-guide/authentication/authentication/ [etcd-readme]: https://github.com/etcd-io/etcd/blob/main/README.md [k8s-doc]: https://kubernetes.io/docs/home/ +[website-repo]: https://github.com/etcd-io/website/tree/main From be9191476cbada620bed74e6f4317b3a341c8983 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Tue, 9 Jan 2024 19:04:50 +0000 Subject: [PATCH 07/10] Addressed first draft review comments. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: dwelsch-esi Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 18 ++-- assessments/0010-etcd/etcd-implementation.md | 98 ++++++++++++-------- 2 files changed, 68 insertions(+), 48 deletions(-) diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index 59cbe2c..dae258a 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -14,13 +14,13 @@ According to CNCF best practices guidelines, effective documentation is a prereq ## Purpose -This document was written to analyze the current state of etcd documentation. It aims to provide project leaders with an informed understanding of their project documentation and to outline an actionable plan for improvement. +This document was written to analyze the current state of etcd documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. The companion document, etcd-impementation.md, outlines an actionable plan for improvement. This document: - Analyzes the current etcd technical documentation and website - Compares existing documentation against the CNCF’s standards -- Recommends a program of key improvements with the largest return on investment +- Recommends a program of key improvements with the largest return on investment. The companion document, etcd-impementation.md, provides specific actionable suggestions and recommendations for overall organization and presentation of documentation ## Scope of analysis @@ -69,7 +69,7 @@ Examples of CNCF documentation that demonstrate the analysis criteria are linked ### Recommendations, requirements, and best practices -Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, in most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how apply documentation best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. +This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. # Project documentation @@ -102,7 +102,7 @@ The *Learning* section, right before *Developer guide* in the ToC, is a catch-al - An overview of the gRPC-based API. - A glossary. -The documentation is not **feature complete**. There are some **undocumented tasks** associated with key features. For example, Kubernetes and Linux installations is not fully documented. The [Authentication][docs-authentication] page is a stub containing only a CLI example. +The documentation is not **feature complete**. There are some **undocumented tasks** associated with key features. For example, Kubernetes and Linux installations are not fully documented. The [Authentication][docs-authentication] page is a stub containing only a CLI example. The documentation contains **instructions** for various features. These instructions include: @@ -114,13 +114,13 @@ The documentation contains **instructions** for various features. These instruct ... and other tasks and procedures. -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 toy server vs. an admin setting up a production server. +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. 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. -Tutorials contain large animated graphics of command line activity. Theser are distracting and degrade the usability of the instructions. +Tutorials contain large animated graphics of command line activity. These are distracting and degrade the usability of the instructions. **Escalation paths** are clearly described in [Reporting bugs](https://etcd.io/docs/v3.5/reporting_bugs/) and [Triage][etcdio-triage]. @@ -132,11 +132,11 @@ There are references to previous releases in the documentation. Most of these sh Benchmarks for down-level versions are available in the current documentation. It's not clear why these old benchmarks haven't been removed from the documentation. -There is an example **installation** on the [etcd Play](http://play.etcd.io/install) server that prsents "an example workflow to install and deploy etcd." This page consists of a form containing parameters (with no explanation of each parameter other than the label) followed by a CLI script that varies depending on the installation type you choose. Presumably you're supposed to run the script to do the install, but there are no clear task instructions at all. It's not clear how this is useful. Novice users will have a hard time with this. Also, why is this information on the demo server at all? Users should be referred to an installation procedure in the documentation. If this represents a separate, automated installation workflow it should be offered as a procedure in the user doc. +There is an example **installation** on the [etcd Play](http://play.etcd.io/install) server that presents "an example workflow to install and deploy etcd." This page consists of a form containing parameters (with no explanation of each parameter other than the label) followed by a CLI script that varies depending on the installation type you choose. Presumably you're supposed to run the script to do the install, but there are no clear task instructions at all. It's not clear how this is useful. Novice users will have a hard time with this. Also, why is this information on the demo server at all? Users should be referred to an installation procedure in the documentation. If this represents a separate, automated installation workflow it should be offered as a procedure in the user doc. ### New user content -There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents. Better would be if it went to an overview page that laid out learning paths for different users ("Start here"). +There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents (ToC). It would be better to link to an overview page that laid out learning paths for different users ("Start here"). 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. @@ -146,7 +146,7 @@ Package manager installation is documented (but not recommended) for Linux and M The *Quickstart* section lists suggested next steps in a *What's next?* heading. However, there is no such section on the *Installation* page, and in neither location is a clear **workflow path** delineated. -There is no **new user signpost** in the documentation. The closest equivalent is the *Quickstart* section, but the Quickstart does not differentiate among user roles (Developer? Operator? Trying to decide whether to adopt?). +There is no **new user signpost** in the documentation. The closest equivalent is the *Quickstart* section, but the Quickstart does not differentiate among user roles (Developer? Operator? Evaluator trying to decide whether to adopt?). The examples in the installation, configuration, and other documentation provide ample code to **copy-paste**. diff --git a/assessments/0010-etcd/etcd-implementation.md b/assessments/0010-etcd/etcd-implementation.md index 6a40dd9..9f2144d 100644 --- a/assessments/0010-etcd/etcd-implementation.md +++ b/assessments/0010-etcd/etcd-implementation.md @@ -11,65 +11,97 @@ For an analysis and general discussion of recommendations on etcd technical docu ## Recommendations, requirements, and best practices -Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, in most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how apply those best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. +This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how to apply those best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: -- Complete and update instructional documentation for important use cases: +- Complete and update instructional documentation: - Describe etcd's user roles (personas). - - Audit the documentation to ensure important use cases are covered. - Document Kubernetes and Linux installation procedures. - Update and clarify quick start and new user workflows. - - Document important tasks as procedures rather than tutorials. - - Clarify which user roles (personas) each task is for. + - Document key tasks as procedures rather than tutorials. + - Clarify which user roles (personas) each task is for. + - Going forward, write release notes for each major and minor release. - Reorganize the documentation. + - 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. - Make instructional documentation (tasks and procedures) easier to find by putting them in their own section (like the tutorials currently are). Rename the "Tutorials" section to "Tasks". The tutorials in the current doc are actually granular tasks. - Rename the "Learning" section to something more descriptive such as "Technical Overview", and move it near the top of the table of contents. - Consolidate all reference information (APIs and Glossary) to a reference-specific section. - Remove information about old software revisions from the current version's docs if it's not necessary for a significant segment of users. This includes upgrade procedures and performance benchmarks. -# Implementation: Complete and update documentation for important use cases +# Implementation: Complete and update documentation -Ensure that task-based documentation is complete and accurate. Common tasks should be described step-by-step in individual descriptions, each with the goal of walking the user through completion of the task. This is distinct from tutorials, which are designed to teach the user how to accomplish a more complex use case. +In general, ensure that task-based documentation is complete and accurate. Write common tasks as step-by-step instructions in individual descriptions, each with the goal of walking the user through completion of the task. This is distinct from tutorials, which are designed to teach the user how to accomplish a more complex use case. -Currently, the "Tutorials" section in the documentation contains tasks that should be documented as such. For example, the [How to access etcd][access-tutorial] tutorial should be two separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on the CLI". +Currently, the "Tutorials" section in the documentation contains tasks that should be documented as such. + +For example, the [How to access etcd][access-tutorial] tutorial should be two separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on the CLI". Name the tasks using gerund phrases ("-ing" form, like "Reading ..." and "Writing ..."). Eliminate "How to", which clutters the heading with a redundant phrase that the user must skip over. -## Audit task-based documentation +## Describe etcd's user roles -We recommend that the project audit the documentation to ensure that instructions exist for all tasks required for mainstream use cases. This includes "getting started" tasks such as installation, configuration, and server tuning; maintenance tasks such as cluster reconfiguration and upgrades and dependency management; product use, including configuration with popular products; and development, especially integrating key storage and retrieval with new products using existing APIs. +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. +- *Developer*: Someone incorporating or integrating etcd into an application or service. ## Write installation instructions for Kubernetes -"Installation as part of Kubernetes installation" is entirely missing ("TBD–Help wanted") on the Installation page. +"Installation as part of Kubernetes installation" is missing. Write and test a procedure for this. ## Write Linux installation instructions -Linux installation instructions are missing ("TDB") from the Installation page. +Linux installation instructions are missing ("TDB") from the Installation page. Write and test a procedure for this. ## 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 -# Reorganize the documentation - -Here are specific recommendations for each section of the documentation. While these are only suggestions, if implemented they will bring the site more in line with documentation best practices. +# Reorganize the documentation -**Quickstart**: Leave here. 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. +## General reorganization + +Reorganized the documentation to contain the following main elements: +- Architectural and system overview (Much of the current "Learning" section) +- "Start here" overview: + - Explanation of user roles and use cases + - Quick start for each user role + - Detailed installation and configuration for each user role (Contents of current "Installation" page) +- Developer guide +- Operator guide +- Troubleshooting +- Reference + - Configuration + - CLIs + - APIs + - Logs and error messages + - Glossary +- Release notes + +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. **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. -**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. Consider moving to the Operations 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 in the system or architecture overview, for example. +**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 labeling each tool or library for what user role will find it useful. +**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. @@ -79,11 +111,11 @@ Here are specific recommendations for each section of the documentation. While t **Discovery service protocol**: This page is duplicated in the Developer Guide; see the note there. Remove it from here. -**Logging conventions**: Move to the Operations Guide. +**Logging conventions**: Move to the Operations Guide or the Reference section. **Golang modules**: Remove from the ToC. Include this information in the architecture overview. -**Learning**: Rename/revamp as "System Overview" or "Architecture Overview" and include sections that explain the conceptual underpinnings of etcd. Move to earlier in ToC, perhaps before "Installation". Recommendations for existing subsections follow. +**Learning**: Rename/revamp as "System Overview" or "Architecture Overview" explaining the conceptual underpinnings of etcd. Move to earlier in ToC, perhaps before "Installation". Recommendations for existing subsections follow. ***Data model***: Include in architecture overview. @@ -101,27 +133,25 @@ Here are specific recommendations for each section of the documentation. While t ***Glossary***: Move to Reference section. -**Developer guide**: This should contain instructional content (tasks, procedures, tutorials) for developers looking to use etcd in an application. Since there are such a large number of APIs and supported interfaces, it might be wise to think about organizing this information by language, at least partially. +**Developer guide**: This should contain instructional content (tasks, procedures, tutorials) for developers looking to use etcd in an application. Since there are such a large number of APIs and supported interfaces, consider organizing this information by language, at least partially. In general, consider rewriting sections in this guide to be step-by-step tasks. ***Discovery service protocol***: What is the use case for this information? If it's to enable a developer to programmatically discover a cluster, leave it here. It might also belong in the Operations guide (but link to the same page, don't copy it), perhaps in the Clustering Guide. -***Set up a local cluster***: Make this the first section in the Developer guide. +***Set up a local cluster***: Make this the first section in the Developer guide. Link from the Developer Quick start rather than sending a developer to the Install page. ***Interacting with etcd***: This page is largely redundant with the Tutorials. Make each task its own page, and consolidate with Tasks as described in "Tutorials" above. -***Why gRPC gateway***: Put the introductory material (that actually 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. +***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. -***System limits*** - -***etcd features*** +***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. ***API reference***: Move to Reference section. ***API reference: concurrency***: Move to Reference section. -**Operations guide**: Any subsection not listed below doesn't need work. In general, though, 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**: 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*** @@ -139,22 +169,12 @@ Here are specific recommendations for each section of the documentation. While t ***Disaster recovery***: Consolidate with other troubleshooting procedures. -***etcd gateway*** - -***gRPC proxy*** - ***Hardware recommendations***: System prerequisite. Move to somewhere before the Cluster Installation section; maybe even put it in a Prereq heading in that section. ***Maintenance***: Maybe provide a more specific title like "Storage maintenance". -***Monitoring etcd*** - -***Performance*** - ***Design of runtime reconfiguration***: Move to architecture overview. -***Runtime reconfiguration*** - ***Supported platforms***: Combine with Hardware recommendations in a System Prerequisites section. ***Versioning***: Rename to "Versioning policy". Add a documentation versioning policy. Move to top of version list. Put a link to this version policy in every release notes. @@ -165,7 +185,7 @@ Here are specific recommendations for each section of the documentation. While t **Upgrading**: Move to the Operations guide. Remove old upgrade paths if they're no longer needed or relevant. -***Upgrading etcd clusters and applications***: As far as I can tell, this page just lists the upbrade pages and isn't needed. +***Upgrading etcd clusters and applications***: As far as I can tell, this page just lists the upgrade pages and isn't needed. **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. From 8d476fd514321dce75c1c1eeb75dcde7177a490f Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Thu, 18 Jan 2024 13:56:52 -0800 Subject: [PATCH 08/10] Add etcd-issues.md A list of issues to add to the website repo to implement the doc improvements. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-issues.md | 298 +++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 assessments/0010-etcd/etcd-issues.md diff --git a/assessments/0010-etcd/etcd-issues.md b/assessments/0010-etcd/etcd-issues.md new file mode 100644 index 0000000..12f728f --- /dev/null +++ b/assessments/0010-etcd/etcd-issues.md @@ -0,0 +1,298 @@ +--- +title: etcd Umbrella Issue +tags: etcd +--- + +# Overview + +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). + - 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. + - 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. + - Rename the "Learning" section to something more descriptive such as "Technical Overview", and move it near the top of the table of contents. + - Consolidate all reference information (APIs and Glossary) to a reference-specific section. + - Remove information about old software revisions from the current version's docs if it's not necessary for a significant segment of users. This includes upgrade procedures and performance benchmarks. + + +# Complete and update instructional documentation + +## Issue: 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*: Someonereponsible for setting up and maintaining a production etcd service. +- *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. + +## Issue: 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. + +Rename each task by removing "How to" and using the "-ing" verb form. Make steps in each task explicit; one-step tasks are okay. + +Rewrite each Tutorial as step-by-step instructions for a single task in an individual description. The goal is to walk the user through the completion of the task. For example, the [How to access etcd][access-tutorial] tutorial should be two separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on the CLI". + + +## Issue: Write installation instructions for Kubernetes + +Write the procedure [Installation as part of Kubernetes installation](install/#installation-as-part-of-kubernetes-installation). + +## Issue: Write Linux installation instructions + +Write [installation instructions for Linux](install/#linux). + +## Issue: 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. + +## Issue: 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. + + +## Issue: Make the Developer Guide task-oriented + +The Developer Guide should contain instructional content (tasks, procedures, tutorials) for developers looking to use etcd in an application. 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 Developer Guide. + +Since there are such a large number of APIs and supported interfaces, consider organizing this information by language or providing an index page to language-specific task and reference pages. + +Following are comments on the existing sections within the Developer Guide. + +### Discovery service protocol + +What is the use case for this information? If it's to enable a developer to programmatically discover a cluster, leave it here. It might also belong in the Operations guide, perhaps in the Clustering Guide (but link to the same page, don't duplicate it). + +### Set up a local cluster + +Make this the first section in the Developer guide. Link from the Developer Quick start -- this is the server install that a developer should see first, not the (Production) Install page. + +### Why gRPC gateway + +This section is mostly about how to use the gRPC gateway. Put the introductory material (that describes why you'd want to use gRPC) in the system overview. Present the rest as a task or tasks in the Tasks section of the Developer Guide. A complete reference to the options should be available in the Reference section. + +### gRPC naming and discovery + +Include the tasks from this section in the gRPC section of the Developer tasks. Include explanatory material in the system overview with the gRPC explanation. + +### etcd features + +This information is a duplicate of the [Features](https://github.com/etcd-io/etcd/blob/main/Documentation/contributor-guide/features.md) maturity information in the repo. Remove from the Developer guide, but reference the repo Features article from the release notes. + + +## Issue: Make the Operations 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. + +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](#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. + + +## 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. + +## Issue: Reorganize the documentation + +Reorganize the documentation to follow this suggested outline: + +- Architectural and system overview (Much of the current "Learning" section) +- "Start here" overview: + - Explanation of user roles and use cases + - Quick start for each user role + - Detailed installation and configuration for each user role (Contents of current "Installation" page plus Local cluster install) +- Developer guide +- Operator guide +- Troubleshooting +- Reference + - Configuration + - CLIs + - APIs + - Logs and error messages + - Glossary +- Release notes + +The goal is to organize the site around the task documentation so that users can find instructions for what they need to do quickly and navigate there directly. Conceptual and reference information should be separate, and linked where necessary to support this goal. + +The following tables contain suggested ToC additions, page deletions, and page moves. Conceptual and task documentation requiring writing or rewriting are described in separate Issues. + +### Add sections + +Sections to be added to the table of contents. + +| Section | Description | +| -- | -- | +| Reference | A library of reference documents: APIs, CLIs, configuration options, and anything else a user might need to look up to complete a task. | +| Troubleshooting | A list of procedures for diagnosing and fixing problems. | +| Release Notes | The cumulative release notes for the major and minor release. See [Release Notes](#add-release-notes-to-new-releases). + +### Remove pages + +Pages to be removed entirely or cannibalized and their contents integrated elsewhere. Links (listed in the table) will need to be removed or updated as well. If the page duplicates or largely overlaps information on another page, that page is listed as "Redundant with". Page URLs are relative to `https://etcd.io/docs/v3.5/`. + +| Page | Links | Redundant with | Suggested action | +| -- | -- | -- | -- | +| demo/ | | op-guide/authentication/authentication/ | Remove | +| dev-internal/discovery_protocol/ | op-guide/clustering/ | dev-guide/discovery_protocol/ | Remove | +| /dev-guide/interacting_v3/ | dev-guide/local_cluster/ | tutorials/*.md | Consolidate under "Tasks". See [Tutorials](#tutorials) | +| op-guide/recovery/ | op-guide/failures/, op-guide/runtime-configuration/, op-guide/runtime-reconf-design/ | | Incorporate into Troubleshooting guide | +| op-guide/data_corruption/ | op-guide/monitoring/ | | Incorporate into Troubleshooting guide | +| upgrades/ | | | Remove or archive old upgrade paths if they're no longer needed or supported. | +| dev-guide/features/ | | | Remove from the Developer guide. See [etcd features](#etcd-features). | + +### Move pages + +Pages to be moved as-is, usually under an organizing heading. Links (listed in the table) will need to be updated. Page URLs are relative to `https://etcd.io/docs/v3.5/`. + +| Page | Links | Suggested action | +| -- | -- | -- | +| metrics/ | | Move to the Operations Guide. | +| learning/glossary/ | | Move to Reference section. | +| tuning/ | op-guide/hardware/, quickstart/ | Move to the Operations Guide. | +| dev-internal/logging/ | | Move to the Reference section. Link from the Operations guide. | +| dev-internal/modules/ | | Move to Architecture overview. | +| 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. | +| 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. | +| op-guide/configuration/ | quickstart/ | Put in the Reference section. | +| upgrades/ | | Move to the Operations guide. | +| 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: Consolidate all reference information + +Consolidate all reference information (APIs and Glossary) 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. + +## Issue: Revise the FAQ + +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 elesewhere. + + +## Issue: 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 the section to earlier in ToC, perhaps before "Installation". + +Recommendations follow for existing subsections of "Learning". + +### Data model + +Include in architecture overview. + +### etcd client design + +Include in architecture overview. Remove the Glossary and merge it into the sitewide Glossary. + +### etcd learner design + +Include in architecture overview. Eliminate references to previous and future releases; describe the current release only. Put comparisons to other releases in the release notes, if relevant. + +### etcd v3 authentication design + +Include in architecture overview. + +### etcd API + +Include in architecture overview. + +### KV API guarantees + +Include in architecture overview. Rename to "Key-value API guarantees". + +### etcd versus other key-value stores + +I think this properly belongs on the webpage as an evaluation tool, but if there's a case for comparing etcd to other KV stores as an instructional strategy, leave it in the system overview. In either case, it needs to be updated. + + +## Issue: Relocate Benchmarks + +Mostly redundant with Benchmark section in Operations guide > Performance. Move any non-redundant info to Performance section in Operations guide. + +Remove old benchmarks if they're no longer needed. + +## Issue: Remove "Upgrading > Upgrading etcd clusters and applications" + +If the intent of this page is to explain upgrade paths that span more than one release, make that clear in an introduction and write an explicit procedure for each path. If such a guide isn't needed, then remove this page. + + + + +[etcd-analysis]: ./etcd-analysis.md +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 +[access-tutorial]: https://etcd.io/docs/v3.5/tutorials/how-to-access-etcd/ From 91634a0f6d1ce6658c9b17a83c1972076575f0b3 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Fri, 19 Jan 2024 13:00:08 +0100 Subject: [PATCH 09/10] chore: update website section Signed-off-by: thisisobate Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index dae258a..3a7613d 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -363,14 +363,14 @@ etcd is a **graduated** project of CNCF. This means that the project should have | Usability, accessibility, and design | 3 - meets standards | | Branding and design | 4 - meets or exceeds standards | | Case studies/social proof | 3 - meets standards | -| SEO, Analytics, and site-local search | | -| Maintenance planning | | -| A11y plan & implementation | | +| SEO, Analytics, and site-local search | 5 - exemplary | +| Maintenance planning | 5 - exemplary | +| A11y plan & implementation | 4 - meets or exceeds standards | | Mobile-first plan & impl. | 3 - meets standards | | HTTPS access & HTTP redirect | 4 - meets or exceeds standards | -| Google Analytics 4 for production only | | -| Indexing allowed for production server only | | -| Intra-site / local search | | +| Google Analytics 4 for production only | 5 - exemplary | +| Indexing allowed for production server only | 5 - exemplary | +| Intra-site / local search | 5 - exemplary | | Account custodians are documented | 4 - meets or exceeds standards | @@ -427,7 +427,7 @@ There is an ADOPTERS.md file in the etcd-io/etcd repository that lists a number ### SEO, Analytics and site-local search -***TBD*** +The website has site-wide search, GA4 enabled, and well indexed on popular search engines; matches perfectly to our criteria. **Analytics:** * Is analytics enabled for the production server? @@ -446,14 +446,15 @@ There is an ADOPTERS.md file in the etcd-io/etcd repository that lists a number The website uses Hugo and Docsy, which are the recommended **website tooling** for CNCF projects. -Web maintainers cultivated? ***TBD*** +Web maintainers cultivated? Maintainers are actively cultivated within the community. The website builds in **reasonable time** on a desktop computer. -Site maintainers have **adequate permissions** to update the website. (I assume. ***TBD***). +Site maintainers have **adequate permissions** to update the website. Maintainers of the [website repository][website-repo] are adequately documented in the OWNERS file in the repo. Approvers and reviewers are listed. + ### Other The website is accessible via **HTTPS**. Requests using **HTTP** are properly redirected to the **HTTPS** URLs. @@ -493,14 +494,12 @@ Consider posting updates and news to the blog more regularly. ### SEO, Analytics and site-local search -***TBD*** +No recommendations. ### Maintenance planning -Consider authorizing contributors to update the website and documentation. - -***TBD*** +No recommendations. ### Other From 84ef660c6825d732c6e9b7d142b3c6259b05cec3 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Fri, 19 Jan 2024 20:39:18 +0100 Subject: [PATCH 10/10] chore: improve SEO and analytics section Signed-off-by: thisisobate Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --- assessments/0010-etcd/etcd-analysis.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/assessments/0010-etcd/etcd-analysis.md b/assessments/0010-etcd/etcd-analysis.md index 3a7613d..6edd2c2 100644 --- a/assessments/0010-etcd/etcd-analysis.md +++ b/assessments/0010-etcd/etcd-analysis.md @@ -430,16 +430,17 @@ There is an ADOPTERS.md file in the etcd-io/etcd repository that lists a number The website has site-wide search, GA4 enabled, and well indexed on popular search engines; matches perfectly to our criteria. **Analytics:** -* Is analytics enabled for the production server? -* Is analytics disabled for all other deploys? -* If your project used Google Analytics, have you migrated to GA4? -* Can Page-not-found (404) reports easily be generated from you site analytics? Provide a sample of the site's current top-10 404s. +* Analytics is enabled for production site. +* Analytics is disabled for all other deploys. +* Project analytics has been migrated to GA4. +* Page-not-found (404) reports can be easily be generated from the site analytics. **Indexing and Search:** -* Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? -* Is local intra-site search available from the website? +* Production site is well indexed. +* Local intra-site search available from the website. -* Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) +**Account custodians** +* Account custodians are not clearly documented. ### Maintenance planning @@ -452,7 +453,7 @@ The website builds in **reasonable time** on a desktop computer. Site maintainers have **adequate permissions** to update the website. -Maintainers of the [website repository][website-repo] are adequately documented in the OWNERS file in the repo. Approvers and reviewers are listed. +Maintainers of the [website repository][website-repo] are adequately documented in the OWNERS file in the repo. Approvers and reviewers are listed. ### Other @@ -494,7 +495,8 @@ Consider posting updates and news to the blog more regularly. ### SEO, Analytics and site-local search -No recommendations. +**Account custodians** +* Areas such as analytics, Google Search Console, site-search (such as Google CSE or Algolia) must have at least one custodian assigned. ### Maintenance planning