diff --git a/analyses/0014-vitess/analysis.md b/analyses/0014-vitess/analysis.md index be739ee..4c963ad 100644 --- a/analyses/0014-vitess/analysis.md +++ b/analyses/0014-vitess/analysis.md @@ -4,6 +4,8 @@ tags: Vitess created: 2025-02-19 modified: 2025-02-19 author: Dave Welsch (dwelsch-esi) +# prettier-ignore +cSpell:ignore: Welsch dwelsch Vitess vitess topo pasteable mysqlshell vtctldclient --- @@ -11,9 +13,9 @@ author: Dave Welsch (dwelsch-esi) ## Introduction This document analyzes the effectiveness and completeness of the -[Vitess][project-website] 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. +[Vitess][project-website] 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. According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first @@ -22,32 +24,30 @@ efforts. ### Purpose -This document was written to analyze the current state of Vitess -documentation. It aims to provide project leaders with an informed -understanding of potential problems in current project documentation. -A second [implementation] document outlines an actionable plan for improvement. -A third document is a [list of issues][issues list] to be added to the project -documentation repository. Theseissues can be taken up by contributors to -improve the documentation. +This document was written to analyze the current state of Vitess documentation. +It aims to provide project leaders with an informed understanding of potential +problems in current project documentation. A second [implementation] document +outlines an actionable plan for improvement. A third document is a [list of +issues][issues list] to be added to the project documentation repository. These +issues can be taken up by contributors to improve the documentation. This document: - Analyzes the current Vitess 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 ### Scope of analysis The documentation discussed here includes the entire contents of the website, -the technical documentation, and documentation for contributors and users on -the Vitess GitHub repository. +the technical documentation, and documentation for contributors and users on the +Vitess GitHub repository. The Vitess website and documentation are written in Markdown and are compiled using the Hugo static site generator with the [Bulma] CSS framework and -apparently served from Netlify. The site does not appear to use a theme, or -uses a default theme (there is no theme given in the configuration file.) -The site's code is stored in its own repository in the Vitess GitHub project. +apparently served from Netlify. The site does not appear to use a theme, or uses +a default theme (there is no theme given in the configuration file.) The site's +code is stored in its own repository in the Vitess GitHub project. #### In scope @@ -58,14 +58,13 @@ The site's code is stored in its own repository in the Vitess GitHub project. #### Out of scope -- Other Vitess repos: https://github.com/vitessio/* (In general, - other Vitess code repos are out of scope) - +- Other Vitess repos: https://github.com/vitessio/* (In general, other Vitess + code repos are out of scope) ### How this document is organized -This document is divided into three sections that represent three major areas -of concern: +This document is divided into three sections that represent three major areas of +concern: - **Project documentation:** concerns documentation for users of the Vitess software, aimed at people who intend to use the project software @@ -79,20 +78,20 @@ Each section begins with summary ratings based on a rubric with appropriate - **Comments**: observations about the existing documentation, with a focus on how it does or does not help Vitess users achieve their goals. -- **Recommendations**: suggested changes that would improve the - effectiveness of the documentation. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. The accompanying [implementation] document 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 are decomposed -into a series of [issues] and entered as GitHub issues in the webiste +into a series of [issues] and entered as GitHub issues in the website [repository][project-doc-website]. ### How to use this document -Readers interested only in actionable improvements should skip this document -and read the **[implementation] plan** and **[issues list]**. +Readers interested only in actionable improvements should skip this document and +read the **[implementation] plan** and **[issues list]**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining @@ -102,8 +101,8 @@ to their area of concern: - [Contributor documentation](#contributor-documentation) - [Website and documentation infrastructure](#website-and-infrastructure) -Examples of CNCF documentation that demonstrate the analysis criteria are -linked from the [criteria] specification. +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria] specification. #### Recommendations, requirements, and best practices @@ -122,13 +121,13 @@ to legal requirements such as copyright and licensing issues. Vitess is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -| Criterion | [Rating (1-5)] | -| -------------------------- | -------------- | -| Information architecture | 2. Needs improvement | -| New user content | 2. Needs improvement | +| Criterion | [Rating (1-5)] | +| -------------------------- | ----------------------------- | +| Information architecture | 2. Needs improvement | +| New user content | 2. Needs improvement | | Content maintainability | 4. Meets or exceeds standards | -| Content creation processes | 1. Not present | -| Inclusive language | 2. Needs improvement | +| Content creation processes | 1. Not present | +| Inclusive language | 2. Needs improvement | ### Comments @@ -148,7 +147,7 @@ The introduction to the Overview could be more helpful to new users. **Feature complete**: Is the documentation feature complete? (i.e., each product feature is documented)? -Yes, the documentation seems to cover all features of Vitesss (as far as I can +Yes, the documentation seems to cover all features of Vitess (as far as I can tell). However, see the following regarding task instructions. **Task instructions**: Are there step-by-step instructions (tasks, tutorials) @@ -179,9 +178,9 @@ procedures. For examples, see **Happy path**: Is the “happy path”/most common use case documented? -Vitess is a complex system with many configuration options. That said, I -believe that setting up and running a production server in Kubernetes is the -main use case, and is covered. +Vitess is a complex system with many configuration options. That said, I believe +that setting up and running a production server in Kubernetes is the main use +case, and is covered. **Isolated, atomic tasks**: Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) @@ -231,8 +230,8 @@ Development versions. #### New user content -**Getting started entry**: Is “getting started” clearly labeled? -(“Getting started”, “Installation”, “First steps”, etc.) +**Getting started entry**: Is “getting started” clearly labeled? (“Getting +started”, “Installation”, “First steps”, etc.) Yes, the Get Started section contains instructions to install, set up, and run Vitess in four different environments (OSes and container solutions). @@ -265,95 +264,103 @@ Yes, there is a Next Steps section at the end of each install except the Docker local install. However, the Next Steps section is perfunctory, pointing in all cases to the Move Tables page in the Migration guide. -**New user signpost**: Is your new user content clearly signposted on your site’s -homepage or at the top of your information architecture? +**New user signpost**: Is your new user content clearly signposted on your +site’s homepage or at the top of your information architecture? -No, there is no clear entry path for new users. They'll probably make their way through -the install and then try to figure out how to implement their migration case (which -probably fits one of the documented scenarios, but there is no clear way for them -to find it). +No, there is no clear entry path for new users. They'll probably make their way +through the install and then try to figure out how to implement their migration +case (which probably fits one of the documented scenarios, but there is no clear +way for them to find it). -**Sample code**: Is there easily copy-pastable sample code or other example content? +**Sample code**: Is there easily copy-pasteable sample code or other example +content? -Yes, command-line examples are plentiful. There is no click-to-copy, however. Users -must highlight and copy manually. +Yes, command-line examples are plentiful. There is no click-to-copy, however. +Users must highlight and copy manually. #### Content maintainability & site mechanics **Searchability**: Is your documentation searchable? -Yes, there is a text Search feature that is limited to the currently displayed version. -It seems to work very well. +Yes, there is a text Search feature that is limited to the currently displayed +version. It seems to work very well. -Search is full-text, so common search terms can result in an unwieldy number of results. +Search is full-text, so common search terms can result in an unwieldy number of +results. -**Localization & i18n directories**: Are you planning for localization/internationalization -with regard to site directory structure? +**Localization & i18n directories**: Are you planning for +localization/internationalization with regard to site directory structure? Yes, there are full versions of the documentation in both English and Chinese. **Localization framework**: Is a localization framework present? -Yes, there seems to be some infrastructure for multiple languages. I'm not sure how -translation is done in Hugo. +Yes, there seems to be some infrastructure for multiple languages. I'm not sure +how translation is done in Hugo. -**Versioning**: Do you have a clearly documented method for versioning your content? +**Versioning**: Do you have a clearly documented method for versioning your +content? -Yes, releasing a new version is scripted. The repository contains instructions. The -latest three released versions are available on the website. +Yes, releasing a new version is scripted. The repository contains instructions. +The latest three released versions are available on the website. #### Content creation processes -**Content creation process**: Is there a clearly documented (ongoing) contribution -process for documentation? +**Content creation process**: Is there a clearly documented (ongoing) +contribution process for documentation? -There are instructions for building and releasing the documentation, as well as detailed -instructions for contributing instructional videos. However, there are no instructions -for contributing technical documentation or fixing documentation issues. +There are instructions for building and releasing the documentation, as well as +detailed instructions for contributing instructional videos. However, there are +no instructions for contributing technical documentation or fixing documentation +issues. -Presumably a contributor can submit a pull request on the website repo to amend or -add to the documentation, but there is no procedure documented. There is a notice -that no grammar or typo fixes are accepted from accounts less than a year old. +Presumably a contributor can submit a pull request on the website repo to amend +or add to the documentation, but there is no procedure documented. There is a +notice that no grammar or typo fixes are accepted from accounts less than a year +old. -**Release process**: Does your code release process account for documentation creation -& updates? +**Release process**: Does your code release process account for documentation +creation & updates? -No, neither the [Contribute](https://vitess.io/docs/contributing/) documentation nor -the [CONTRIBUTING.md](https://github.com/vitessio/vitess/blob/main/CONTRIBUTING.md) -file in the product repo describes how to contribute documentation. There is no Contribution -section in the website repo. +No, neither the [Contribute](https://vitess.io/docs/contributing/) documentation +nor the +[CONTRIBUTING.md](https://github.com/vitessio/vitess/blob/main/CONTRIBUTING.md) +file in the product repo describes how to contribute documentation. There is no +Contribution section in the website repo. **Review and approval**: Who reviews and approves documentation pull requests? -Unknown. The Governance document gives detailed descriptions of the User, Contributor, -and Maintainer roles. It does not mention documentation explicitly except as one of -the contributor tasks. +Unknown. The Governance document gives detailed descriptions of the User, +Contributor, and Maintainer roles. It does not mention documentation explicitly +except as one of the contributor tasks. **Site owner and maintainer**: Does the website have a clear owner/maintainer? -No, the main project repo lists maintainers, along with areas of expertise. None of -them lists documentation as an area of expertise. There is no owner information on -the website repo. +No, the main project repo lists maintainers, along with areas of expertise. None +of them lists documentation as an area of expertise. There is no owner +information on the website repo. #### Inclusive language -**Non-inclusive phrases**: Are customer-facing utilities, endpoints, class names, -or feature names free of non-recommended words as documented by the +**Non-inclusive phrases**: Are customer-facing utilities, endpoints, class +names, or feature names free of non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website? -Not entirely, but there have clearly been attempts to correct non-inclusive language -on the site. For example, “primary” replaces “master” to describe the database of -record in the Vitess product. Some non-inclusive language remains. Examples: -“sanity check”; “master database” (these can be found using the website's Search function). +Not entirely, but there have clearly been attempts to correct non-inclusive +language on the site. For example, “primary” replaces “master” to describe the +database of record in the Vitess product. Some non-inclusive language remains. +Examples: “sanity check”; “master database” (these can be found using the +website's Search function). -Of course, some of this language exists in product command elements and outputs that -cannot be changed in the documentation without first eliminating them in code (command -line options, for example). +Of course, some of this language exists in product command elements and outputs +that cannot be changed in the documentation without first eliminating them in +code (command line options, for example). -**Ableist language**: "Is the project free of language like 'simple', 'easy', etc.?" +**Ableist language**: "Is the project free of language like 'simple', 'easy', +etc.?" -No. A few examples exist. These should be evaluated and replaced on a case by case -basis. +No. A few examples exist. These should be evaluated and replaced on a case by +case basis. ### Recommendations @@ -361,17 +368,17 @@ basis. **Get Started** -Write an introduction on the [Get Started](https://vitess.io/docs/21.0/get-started/) -landing page. This introduction should outline a path for new users something like -the following: +Write an introduction on the +[Get Started](https://vitess.io/docs/21.0/get-started/) landing page. This +introduction should outline a path for new users something like the following: 1. Install test environment 2. Configure test environment 3. Test Vitess -After this familiarization process, there should be a a pointer to a User Guide processes -that walk the reader through the product's "happy path" in a more or less linear path -(a series of tasks). That might look something like this: +After this familiarization process, there should be a a pointer to a User Guide +processes that walk the reader through the product's "happy path" in a more or +less linear path (a series of tasks). That might look something like this: 1. Plan production installation 2. Install production version @@ -380,105 +387,112 @@ that walk the reader through the product's "happy path" in a more or less linear 5. Run queries 6. Maintain and add cells/shards/databases. -The "Next steps" sections on the test installation pages should point readers to new-user -configuration and testing procedures. +The "Next steps" sections on the test installation pages should point readers to +new-user configuration and testing procedures. -The "Next steps" section on the production installation page should point users to -whatever is next in the User Guide documentation. This can be more than one path. -Make it conditional based on the task a reader might want to accomplish after installation: -Test the installation? Plan a cluster? Something else? +The "Next steps" section on the production installation page should point users +to whatever is next in the User Guide documentation. This can be more than one +path. Make it conditional based on the task a reader might want to accomplish +after installation: Test the installation? Plan a cluster? Something else? **Conceptual Info** - Clarify the beginning of the [Overview](https://vitess.io/docs/21.0/overview/whatisvitess/) -("What is ...") The introduction from the README in the [code repository][project-website] -is pretty good: +Clarify the beginning of the +[Overview](https://vitess.io/docs/21.0/overview/whatisvitess/) ("What is ...") +The introduction from the README in the [code repository][project-website] is +pretty good: -> Vitess is a cloud-native horizontally-scalable distributed database system that -is built around MySQL. +> Vitess is a cloud-native horizontally-scalable distributed database system +> that is built around MySQL. Or the introduction that this replaced: -> Vitess is a database clustering system for horizontal scaling of MySQL through generalized -sharding. +> Vitess is a database clustering system for horizontal scaling of MySQL through +> generalized sharding. **Tasks** -The User Guides page *says* "Task-based guides for common usage scenarios". That's -the right idea, but implementation must be improved if readers are to find and carry -out the documented tasks. +The User Guides page _says_ "Task-based guides for common usage scenarios". +That's the right idea, but implementation must be improved if readers are to +find and carry out the documented tasks. The User Guides require three types of changes to maximize their effectiveness: + - Rename - Rewrite - Reorganize -*Rename* +_Rename_ + +Rename the individual pages in the User Guides to reflect the tasks that are +described there. Use verbs ending in "-ing" (along with a noun that describes +the object of the task, if applicable). This helps readers find the right +content in at least two ways: -Rename the individual pages in the User Guides to reflect the tasks that are described -there. Use verbs ending in "-ing" (along with a noun that describes the object of -the task, if applicable). This helps readers find the right content in at least two -ways: - Makes the TOC more coherent -- Gives meaningful results in the sitewide Search +- Gives meaningful results in the site-wide Search -Here are three examples from the -[same page] -(https://vitess.io/docs/21.0/user-guides/configuration-basic/global-topo/) -(the content of these sections is not considered here): -- *Choosing a TopoRoot*: A good title. Describes the task ("choosing") and the object - of the task ("TopoRoot"). -- *Moving to a different TopoServer*: A good title. Describes the task ("moving"). - Normally I'd recommend a more direct reference to the object -- - "Moving TopoServers" -- but in this case the phrase ".. to a different TopoServer" - removes ambiguity. -- *Backups*: Not a helpful title. It's not clear or what you're backing up or what - what aspect of the backups you're talking about. I'd change this to "Backing - up TopoServer data". +Here are three examples from the [same page] +(https://vitess.io/docs/21.0/user-guides/configuration-basic/global-topo/) (the +content of these sections is not considered here): + +- _Choosing a TopoRoot_: A good title. Describes the task ("choosing") and the + object of the task ("TopoRoot"). +- _Moving to a different TopoServer_: A good title. Describes the task + ("moving"). Normally I'd recommend a more direct reference to the object -- + "Moving TopoServers" -- but in this case the phrase ".. to a different + TopoServer" removes ambiguity. +- _Backups_: Not a helpful title. It's not clear or what you're backing up or + what what aspect of the backups you're talking about. I'd change this to + "Backing up TopoServer data". Also on the Global TopoServer page, by the way: -> The following command line options are required for every Vitess component: +> The following command line options are required for every Vitess component: > -> ```--topo_implementation=etcd2 --topo_global_server_address= - --topo_global_root=/vitess/global``` +> ````--topo_implementation=etcd2 --topo_global_server_address= +> --topo_global_root=/vitess/global``` > -> To avoid repetition we will use in our examples to signify the above - flags. +> To avoid repetition we will use in our examples to signify the above +> flags. +> ```` -Remove this. The "" placeholder does not seem to have been implemented. -There are no mentions of " elsewhere in the documentation, and in any -case each would have to refer back to this page. +Remove this. The "" placeholder does not seem to have been +implemented. There are no mentions of " elsewhere in the +documentation, and in any case each would have to refer back to this page. -*Rewrite* +_Rewrite_ -A reader typically consults the User Guide to find out how to do something. The User -Guides should consist primarily of procedures. +A reader typically consults the User Guide to find out how to do something. The +User Guides should consist primarily of procedures. -There are some Vitess features for which the User Guide gives a description but does -not provide adequate instructions for their use. +There are some Vitess features for which the User Guide gives a description but +does not provide adequate instructions for their use. -For example, look at [Creating a Backup](https://vitess.io/docs/21.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup/) +For example, look at +[Creating a Backup](https://vitess.io/docs/21.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup/) -This page appears to be well named ("Creating a Backup" is a descriptive task title) -and properly placed (it resides in a logical location in the User Guide). However, -the page itself doesn't contain an actual command or set of steps to back up a database: -There is no actual command line given between *Configuration* and -*Common Errors and Resolutions* The page's author might assume that it's implied, -but it should be presented explicitly as a step in the procedure. +This page appears to be well named ("Creating a Backup" is a descriptive task +title) and properly placed (it resides in a logical location in the User Guide). +However, the page itself doesn't contain an actual command or set of steps to +back up a database: There is no actual command line given between +_Configuration_ and _Common Errors and Resolutions_ The page's author might +assume that it's implied, but it should be presented explicitly as a step in the +procedure. -Further down the page, another backup option, *Using mysqlshell*, has the same shortcomings: -No actual command is presented. +Further down the page, another backup option, _Using mysqlshell_, has the same +shortcomings: No actual command is presented. -Instead, write these pages as step-by-step descriptions of how to perform a task. -Each step should be a concise instruction, with any required instruction or text illustrated -and explained (much of the time, this is a monospace code/CLI block displaying the -command-line instruction to use). This can be an example, but only if it is obvious -how the reader should use the command. Other times, it means showing the required -form of the command, with placeholders for parameters, and explaining those parameters -in the following text. +Instead, write these pages as step-by-step descriptions of how to perform a +task. Each step should be a concise instruction, with any required instruction +or text illustrated and explained (much of the time, this is a monospace +code/CLI block displaying the command-line instruction to use). This can be an +example, but only if it is obvious how the reader should use the command. Other +times, it means showing the required form of the command, with placeholders for +parameters, and explaining those parameters in the following text. -The [Creating a cell](https://vitess.io/docs/21.0/user-guides/configuration-basic/create-cell/) +The +[Creating a cell](https://vitess.io/docs/21.0/user-guides/configuration-basic/create-cell/) page shows a CLI command: > ``` @@ -488,8 +502,8 @@ page shows a CLI command: > cell1 > ``` -It's not clear if `/vitess/cell1` is a user-definable parameter or not. The server -address placeholder, ``, is not defined in the text. +It's not clear if `/vitess/cell1` is a user-definable parameter or not. The +server address placeholder, ``, is not defined in the text. Here's how I'd rewrite it, defining placeholders for the parameters: @@ -501,6 +515,7 @@ Here's how I'd rewrite it, defining placeholders for the parameters: > ``` > > where: +> > - is the root directory of the server installation > - is the IP address of the topo server @@ -510,154 +525,169 @@ Here's an outline for a one-page procedure writeup: - Title ("ABCing XYZ") - Context (Describe where the procedure fits in the overall use case) - - Prerequisites (Hardware and software requirements, dependencies, procedures that - must be completed first) + - Prerequisites (Hardware and software requirements, dependencies, procedures + that must be completed first) - Procedure ("To ABC an XYZ, do the following.") - - Step 1 (*One* CLI command, or action. Don't combine actions.) + - Step 1 (_One_ CLI command, or action. Don't combine actions.) - Step 2 (etc.) - - Result (Optional - include only if there's something remarkable about the outcome.) - - Next Steps (What procedure or use case typically follows this. If it depends on - context, explain the options.) + - Result (Optional - include only if there's something remarkable about the + outcome.) + - Next Steps (What procedure or use case typically follows this. If it depends + on context, explain the options.) -*Reorganize* +_Reorganize_ -Ensure that the various sections of the User Guide cover all usage scenarios. Reorganize -the User Guide: +Ensure that the various sections of the User Guide cover all usage scenarios. +Reorganize the User Guide: + +First, organize by user role, if there are distinct roles. As I understand it, +there are basically three user roles in Vitess: -First, organize by user role, if there are distinct roles. As I understand it, there -are basically three user roles in Vitess: - Vitess admin - Database admin - Application developer - User roles traditionally are the basis for a "User Guide": +User roles traditionally are the basis for a "User Guide": + - Admin Guide - DBA Guide - Programmer's Guide - etc. -Within roles, organize the tasks around use cases. Don't be afraid to split up tasks -that use the same tool (CLI or other). In other words, pick and choose commands and -actions that server a use case rather than trying to document everything you can do -with the command in one place. (There is a place to exhaustively document a tool, -but that's in the Reference, not a User Guide.) +Within roles, organize the tasks around use cases. Don't be afraid to split up +tasks that use the same tool (CLI or other). In other words, pick and choose +commands and actions that server a use case rather than trying to document +everything you can do with the command in one place. (There is a place to +exhaustively document a tool, but that's in the Reference, not a User Guide.) -The existing Vitess User Guides are already partially organized around user roles, -but they can be regrouped. In any case, make the user roles explicit: +The existing Vitess User Guides are already partially organized around user +roles, but they can be regrouped. In any case, make the user roles explicit: + +_Vitess admin_: -*Vitess admin*: - Configuration - Running in production - Operational - Migration -*DBA*: +_DBA_: + - VSchema and Query Serving - SQL statement analysis - Making schema changes -*Application programmer*: +_Application programmer_: + - Query serving -- Making schema changes (don't duplicate the section here. Instead provide links to - any tasks that are identical) +- Making schema changes (don't duplicate the section here. Instead provide links + to any tasks that are identical) - Query optimization -(Again, these are my understanding of the Vitess user roles. Adjust the details if -they're different. +(Again, these are my understanding of the Vitess user roles. Adjust the details +if they're different. **Troubleshooting** -Consolidate all troubleshooting information into a Troubleshooting Guide. Or, create -one troubleshooting guide per user guide/user role. In either case, create an escalation -path for any problems with a task (the escalation path might be: -*troubleshooting procedure > Slack Channel > project Issue*). Get rid of the -[VReplication FAQ](https://vitess.io/docs/21.0/reference/vreplication/faq/) -in the reference section and put the information in a troubleshooting section. +Consolidate all troubleshooting information into a Troubleshooting Guide. Or, +create one troubleshooting guide per user guide/user role. In either case, +create an escalation path for any problems with a task (the escalation path +might be: _troubleshooting procedure > Slack Channel > project Issue_). Get rid +of the +[VReplication FAQ](https://vitess.io/docs/21.0/reference/vreplication/faq/) in +the reference section and put the information in a troubleshooting section. **Glossary** -Write a glossary. This is different from the "Concepts" page – the explanations of -terms is less in-depth. The glossary contains not just key terms but any word or phrase -that the reader might not know: abbreviations and acronyms, definitions of Vitess-specific -terms, and explanations of jargon used in Vitess ("topo", for example). +Write a glossary. This is different from the "Concepts" page – the explanations +of terms is less in-depth. The glossary contains not just key terms but any word +or phrase that the reader might not know: abbreviations and acronyms, +definitions of Vitess-specific terms, and explanations of jargon used in Vitess +("topo", for example). **Other recommendations** -Rename ["Reference > Programs"](https://vitess.io/docs/21.0/reference/programs/) to -"Command line reference" or "Tools reference". Consider splitting into two or more -sections by type of application: by function or user role. CLIs should be labeled -as such and separated from GUI tools. +Rename ["Reference > Programs"](https://vitess.io/docs/21.0/reference/programs/) +to "Command line reference" or "Tools reference". Consider splitting into two or +more sections by type of application: by function or user role. CLIs should be +labeled as such and separated from GUI tools. #### New user content -Is there an alternative to Kubernetes for running in production? Explain. Give an -explicit list of supported OSes. This can be done by expanding the Get Started landing -page (see [Information Architecture > Get Started](#information-architecture)). +Is there an alternative to Kubernetes for running in production? Explain. Give +an explicit list of supported OSes. This can be done by expanding the Get +Started landing page (see +[Information Architecture > Get Started](#information-architecture)). Rewrite installation instructions as step by step procedures. Expand the production install [Next Step](https://vitess.io/docs/21.0/get-started/operator/#next-steps) -section to accomodate different configurations (conversion, green field, etc.). Differentiate -between Next Steps for test/development installations and production installation. +section to accommodate different configurations (conversion, green field, etc.). +Differentiate between Next Steps for test/development installations and +production installation. -Put enough information on the Get Started landing page to orient new users as described -in [Information Architecture > Get Started](#information-architecture). +Put enough information on the Get Started landing page to orient new users as +described in +[Information Architecture > Get Started](#information-architecture). Rename sections so that it's easier to find the right page in Search: + - Use "-ing" verbs for task pages as previously described - Use the word "reference" in CLI references - Use nouns for architectural components, features, and concepts #### Content maintainability & site mechanics -No recommendations. Technical aspects of infrastructure and maintenance seem excellent. +No recommendations. Technical aspects of infrastructure and maintenance seem +excellent. #### Content creation processes -There is no documnetation for website and tech doc content creation. Such documentation -could include: +There is no documentation for website and tech doc content creation. Such +documentation could include: + - Instructions for documenting tasks associated with new features - Instructions for fixing documentation issues -- Templates for task writeups and command references +- Templates for task write-ups and command references - Guidelines for amending conceptual information with new features - A style manual - A review and approval process, separate from the code process - A link from the code contribution instructions to the doc instructions -- A maintainer designated to be responsible for website maintenance and for documentation -changes and updates +- A maintainer designated to be responsible for website maintenance and for + documentation changes and updates - Getting started instructions for new documentation contributors -In practice, open source projects rarely contain all this information. At a minimum, -document the following processes for contributors: +In practice, open source projects rarely contain all this information. At a +minimum, document the following processes for contributors: + - Documenting a new release - - Generating, testing, and deploying the new release docs, including how to publish -release notes + - Generating, testing, and deploying the new release docs, including how to + publish release notes - Demoting, archiving, or deleting down-level releases - Creating a doc issue - Fixing and closing a doc issue - How to contact the website and documentation maintainer with questions - Getting started instructions for new documentation contributors -These processes should address documentation-specific concerns, not just parrot the -code release procedures (although there may be many of the same steps). +These processes should address documentation-specific concerns, not just parrot +the code release procedures (although there may be many of the same steps). #### Inclusive language -Search the document for non-inclusive terms, especially tier-1 and tier-2 terms per -the [Inclusive Naming Initiative](https://inclusivenaming.org/). Replace with recommended -language where possible. +Search the document for non-inclusive terms, especially tier-1 and tier-2 terms +per the [Inclusive Naming Initiative](https://inclusivenaming.org/). Replace +with recommended language where possible. ## Contributor documentation Vitess is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -| Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | -| Communication methods documented | 3. Meets standards | -| Beginner friendly issue backlog | 2. Needs improvement | -| “New contributor” getting started content | 2. Needs improvement | +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | ----------------------------- | +| Communication methods documented | 3. Meets standards | +| Beginner friendly issue backlog | 2. Needs improvement | +| “New contributor” getting started content | 2. Needs improvement | | Project governance documentation | 4. Meets or exceeds standards | ### Comments @@ -667,17 +697,18 @@ Contributor Documentation rubric. #### Communication methods documented -**Text communication channel**: Is there a Slack/Discord/Discourse/etc. community -and is it prominently linked from your website? +**Text communication channel**: Is there a Slack/Discord/Discourse/etc. +community and is it prominently linked from your website? Yes, the community page lists a Slack channel. -**Repository link**: Is there a direct link to your GitHub organization/repository? +**Repository link**: Is there a direct link to your GitHub +organization/repository? Yes, the community page and the footer list the GitHub page for the product. -**Project meetings**: Are weekly/monthly project meetings documented? Is it clear -how someone can join those meetings? +**Project meetings**: Are weekly/monthly project meetings documented? Is it +clear how someone can join those meetings? Yes, the community page lists the monthly community meetings. @@ -689,19 +720,20 @@ No, there does not appear to be an email list. **Issue triage**: Are docs issues well-triaged? -No, there does not appear to be any mechanism for prioritizing issues in the GitHub -repo. +No, there does not appear to be any mechanism for prioritizing issues in the +GitHub repo. -**Good first issues**: Is there a clearly marked way for new contributors to make -code or documentation contributions (i.e. a “good first issue” label)? +**Good first issues**: Is there a clearly marked way for new contributors to +make code or documentation contributions (i.e. a “good first issue” label)? Yes, there is a “good first issue” label in the website repo issues list. -**Issue documentation**: Are issues well-documented (i.e., more than just a title)? +**Issue documentation**: Are issues well-documented (i.e., more than just a +title)? -Yes, issues seem to have at least a paragraph description. However, there is no issues -template or guidelines for documenting issues, so the quality of the descriptions -is inconsistent. +Yes, issues seem to have at least a paragraph description. However, there is no +issues template or guidelines for documenting issues, so the quality of the +descriptions is inconsistent. **Issue freshness**: Are issues maintained for staleness? @@ -709,13 +741,14 @@ No, the oldest open issue is over 6 years old. #### New contributor getting started content -**Community featured on website**: Do you have a community repository or section on -your website? +**Community featured on website**: Do you have a community repository or section +on your website? -Yes, there is a Community link in the site’s menu bar, leading to the Community page. +Yes, there is a Community link in the site’s menu bar, leading to the Community +page. -**New contributor document**: Is there a document specifically for new contributors/your -first contribution? +**New contributor document**: Is there a document specifically for new +contributors/your first contribution? No, I could not find a new contributor's document. @@ -737,7 +770,8 @@ No recommendations. #### Beginner friendly issue backlog -Create an issue template to ensure that issue descriptions are consistent and complete. +Create an issue template to ensure that issue descriptions are consistent and +complete. Go through the issues backlog and close or update old issues. @@ -754,16 +788,16 @@ No recommendations. Vitess is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -| Criterion | [Rating (1-5)] | -| ------------------------------------------- | -------------- | -| Single-source for all files | 5. Exemplary | -| Meets min website req. (for maturity level) | 2. Needs improvement | -| Usability, accessibility, and design | 3. Meets standards | +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | ----------------------------- | +| 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 | 2. Needs improvement | -| SEO, Analytics, and site-local search | TBD | -| Maintenance planning | 2. Needs improvement | -| HTTPS access & HTTP redirect | 5. Exemplary | +| Case studies/social proof | 2. Needs improvement | +| SEO, Analytics, and site-local search | TBD | +| Maintenance planning | 2. Needs improvement | +| HTTPS access & HTTP redirect | 5. Exemplary | ### Comments @@ -772,8 +806,8 @@ and documentation infrastructure rubric. #### Single source -**Single source for docs**: Does the project have a single source for documentation? -If not, is there a reason? +**Single source for docs**: Does the project have a single source for +documentation? If not, is there a reason? Yes, the website and tech doc content are all in one GitHub repo. @@ -781,19 +815,19 @@ Yes, the website and tech doc content are all in one GitHub repo. **Website guidelines**: Are all guidelines satisfied? -Yes, the website mostly meets all criteria for a CNCF graduated website, including -hosting, copyright, CNCF branding, and trademark. +Yes, the website mostly meets all criteria for a CNCF graduated website, +including hosting, copyright, CNCF branding, and trademark. **Docs analysis**: Are all follow-up actions addressed? -Pending: There is no reason to believe the Vitess team won’t follow through on recommendations -in this analysis. +Pending: There is no reason to believe the Vitess team won’t follow through on +recommendations in this analysis. **Project doc: stakeholders**: Are all stakeholder needs identified? -No, roles are not explicitly defined in the documentation. There is some differentiation -among roles implicit in the docs (admin permissions, RBAC support, etc.), but it is -not used to organize the content. +No, roles are not explicitly defined in the documentation. There is some +differentiation among roles implicit in the docs (admin permissions, RBAC +support, etc.), but it is not used to organize the content. **Project doc: hosting**: Hosted directly. @@ -801,8 +835,8 @@ Yes, the site is hosted on Netlify. **Project doc: user docs**: Fully addresses needs of key stakeholders? -Yes, the documentation probably addresses all stakeholder needs, but is not organized -so that users can find the docs efficiently. +Yes, the documentation probably addresses all stakeholder needs, but is not +organized so that users can find the docs efficiently. #### Usability, accessibility and devices @@ -814,23 +848,26 @@ Yes, the site seems to adapt well to small screen use. Yes, documentation pages are readable on all tested platforms and screen sizes. -**Mobile navigability**: Are all / most website features accessible from mobile -- -such as the top-nav, site search and in-page table of contents? +**Mobile navigability**: Are all / most website features accessible from mobile +-- such as the top-nav, site search and in-page table of contents? Most website features are accessible from mobile. -**Mobile-first design**: Might a [mobile-first] design make sense for your project? +**Mobile-first design**: Might a [mobile-first] design make sense for your +project? -No, this project might occasionally be accessed on mobile but it doesn't seem likely -to be the main use case. +No, this project might occasionally be accessed on mobile but it doesn't seem +likely to be the main use case. -**Color contrast**: Are color contrasts significant enough for color-impaired readers? +**Color contrast**: Are color contrasts significant enough for color-impaired +readers? Yes, text is black on white. Font is a very legible sans serif. **Keyboard-only**: Are most website features usable using a keyboard only? -Yes, most features are usable. However, tab navigation is awkward and time-consuming. +Yes, most features are usable. However, tab navigation is awkward and +time-consuming. **Text-to-speech**: Does text-to-speech offer listeners a good experience? @@ -841,40 +878,41 @@ Text-to-speech was not tested. **Recognizable brand**: Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? -Yes, the site has a consistent design. The orange “layered sheets” logo is recognizable. +Yes, the site has a consistent design. The orange “layered sheets” logo is +recognizable. **Consistent branding**: Is the brand used across the website consistently? -Yes, branding is used cosistently. +Yes, branding is used consistently. **Typography**: Is the website’s typography clean and well-suited for reading? -Yes, the font is a little small in places, but overall legible. Font scales gracefully -when magnified in the browser. +Yes, the font is a little small in places, but overall legible. Font scales +gracefully when magnified in the browser. #### Case studies & social proof -**Case studies**: Are there case studies available for the project and are they documented -on the website? +**Case studies**: Are there case studies available for the project and are they +documented on the website? -No, I did not see any case studies. Some of them many videos might contain case studies, -though. +No, I did not see any case studies. Some of them many videos might contain case +studies, though. **Testimonials**: Are there user testimonials available? -No, there do not seem to be testimonials available on the site. The logo wall does -not have live links. +No, there do not seem to be testimonials available on the site. The logo wall +does not have live links. **Active blog**: Is there an active project blog? -Yes, there is a blog. The last entry was two months ago, but it seems to be updated -semi-regularly. +Yes, there is a blog. The last entry was two months ago, but it seems to be +updated semi-regularly. -**Community talks listed**: Are there community talks for the project and are they -present on the website? +**Community talks listed**: Are there community talks for the project and are +they present on the website? -Yes, there are many videos on the “Learning Resources” page, containing a variety -of topics including community talks. +Yes, there are many videos on the “Learning Resources” page, containing a +variety of topics including community talks. **Logo wall**: Is there a logo wall of users/participating organizations? @@ -882,63 +920,70 @@ Yes, there is a substantial logo wall on the product landing page. #### SEO, Analytics and site-local search -**Analytics on production site**: Analytics: Is analytics enabled for the production -server? +**Analytics on production site**: Analytics: Is analytics enabled for the +production server? + - TBD - TBD -**Analytics disabled for non-production sites**: Analytics: Is analytics disabled -for all other deploys? +**Analytics disabled for non-production sites**: Analytics: Is analytics +disabled for all other deploys? + - TBD - TBD -**Google analytics: GA4**: Analytics: If your project used Google Analytics, have -you migrated to GA4? +**Google analytics: GA4**: Analytics: If your project used Google Analytics, +have you migrated to GA4? + - TBD - TBD -**404 reports**: Analytics: Can Page-not-found (404) reports easily be generated from -you site analytics? Provide a sample of the site's current top-10 404s. +**404 reports**: Analytics: Can Page-not-found (404) reports easily be generated +from you site analytics? Provide a sample of the site's current top-10 404s. + - TBD - TBD -**Site indexing on production server**: Is site indexing supported for the production -server? +**Site indexing on production server**: Is site indexing supported for the +production server? + - TBD - TBD -**Site indexing disabled on non-default content**: Is site indexing disabled for website -previews and - TBD +**Site indexing disabled on non-default content**: Is site indexing disabled for +website previews and - TBD + - TBD **Intra-site search**: Is local intra-site search available from the website? -Yes, the site text search funciton works well. +Yes, the site text search function works well. -**Analytics custodians documented**: Are the current custodian(s) of the following -accounts clearly documented: analytics, Google Search Console, site-search (such as -Google CSE or Algolia) +**Analytics custodians documented**: Are the current custodian(s) of the +following accounts clearly documented: analytics, Google Search Console, +site-search (such as Google CSE or Algolia) No documentation maintainers of any sort are credited. #### Maintenance planning -**Well supported website tooling**: Is your website tooling well supported by the -community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our -recommended tech stack?) +**Well supported website tooling**: Is your website tooling well supported by +the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF +projects (our recommended tech stack?) -Yes, the site is implented using Hugo, CNCF's recommended site generator, and hosted -on Netlify. +Yes, the site is implemented using Hugo, CNCF's recommended site generator, and +hosted on Netlify. -**Cultivating website maintainers**: Are you actively cultivating website maintainers -from within the community? +**Cultivating website maintainers**: Are you actively cultivating website +maintainers from within the community? -Unknown. There is no documented evidence of recruitment on the website or in the repository. +Unknown. There is no documented evidence of recruitment on the website or in the +repository. **Site build times**: Are site build times reasonable? -I did not try building the site but have no reason to believe that the build time -is excessive. +I did not try building the site but have no reason to believe that the build +time is excessive. **Maintainer permissions**: Do site maintainers have adequate permissions? @@ -952,7 +997,8 @@ Yes, all site pages use HTTPS. **HTTP redirect**: Does HTTP access, if any, redirect to HTTPS? -Yes, pages requested using HTTP are redirected to existing HTTPS pages seamlessly. +Yes, pages requested using HTTP are redirected to existing HTTPS pages +seamlessly. ### Recommendations @@ -962,8 +1008,8 @@ No recommendations. #### Minimal website requirements -Identify stakeholder and user roles. Orgainize task documentation around user roles -(see [Information architecture](#information-architecture)). +Identify stakeholder and user roles. Organize task documentation around user +roles (see [Information architecture](#information-architecture)). #### Usability, accessibility and devices @@ -975,8 +1021,8 @@ No recommendations. #### Case studies/social proof -Include case studies and testimonials on the product website. If these are already -among the video content, tag them and feature them on the landing page. +Include case studies and testimonials on the product website. If these are +already among the video content, tag them and feature them on the landing page. Update blog content at least monthly. @@ -1008,9 +1054,9 @@ The numeric rating values used in this document are as follows: ### References -[criteria]: ../criteria.md -[implementation]: ./implementation.md -[issues list]: ./issues-list.md +[criteria]: ../../docs/analysis/criteria.md +[implementation]: ./implementation.md?no-link-check +[issues list]: ./issues-list.md?no-link-check [project-doc-website]: ?https://vitess.io/docs/ [project-website]: ?https://vitess.io/ [Rating (1-5)]: #rating-values