diff --git a/.cspell.yml b/.cspell.yml
index 2e643c2..714de68 100644
--- a/.cspell.yml
+++ b/.cspell.yml
@@ -21,6 +21,10 @@ ignorePaths:
# ignoreRegExpList:
# - CodeBlock
words:
+ - backstore
- CNCF
- Docsy
+ - keda
+ - kedacore
- techdocs
+ - toto
diff --git a/.markdown-link-check.json b/.markdown-link-check.json
index 0d31049..f2239ee 100644
--- a/.markdown-link-check.json
+++ b/.markdown-link-check.json
@@ -2,6 +2,9 @@
"ignorePatterns": [
{
"pattern": "^http://localhost"
+ },
+ {
+ "pattern": "^#"
}
],
"timeout": "3s",
diff --git a/.prettierignore b/.prettierignore
index a8e0f31..2709d58 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -3,8 +3,6 @@
# temporary
# Until https://github.com/cncf/techdocs/pull/229 is merged
-assessments
+analyses
docs
/README.md
-
-assistance.md
diff --git a/README.md b/README.md
index fc1f3b7..eb3ed1d 100644
--- a/README.md
+++ b/README.md
@@ -35,9 +35,7 @@ We store ongoing meeting notes in a [Google doc](https://docs.google.com/documen
## Assistance program for technical documentation
-The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][].
-
-[assistance-program]: ./assistance.md
+The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance program](docs/assistance.md).
### Resources
diff --git a/assessments/0001-contour.md b/analyses/0001-contour.md
similarity index 100%
rename from assessments/0001-contour.md
rename to analyses/0001-contour.md
diff --git a/assessments/0002-notary-project.md b/analyses/0002-notary-project.md
similarity index 100%
rename from assessments/0002-notary-project.md
rename to analyses/0002-notary-project.md
diff --git a/assessments/0003-krator.md b/analyses/0003-krator.md
similarity index 100%
rename from assessments/0003-krator.md
rename to analyses/0003-krator.md
diff --git a/assessments/0004-tremor.md b/analyses/0004-tremor.md
similarity index 100%
rename from assessments/0004-tremor.md
rename to analyses/0004-tremor.md
diff --git a/assessments/0005-fluxcd.md b/analyses/0005-fluxcd.md
similarity index 100%
rename from assessments/0005-fluxcd.md
rename to analyses/0005-fluxcd.md
diff --git a/assessments/0006-gateway-api.md b/analyses/0006-gateway-api.md
similarity index 100%
rename from assessments/0006-gateway-api.md
rename to analyses/0006-gateway-api.md
diff --git a/assessments/0007-porter.md b/analyses/0007-porter.md
similarity index 100%
rename from assessments/0007-porter.md
rename to analyses/0007-porter.md
diff --git a/assessments/0008-backstage/README.md b/analyses/0008-backstage/README.md
similarity index 100%
rename from assessments/0008-backstage/README.md
rename to analyses/0008-backstage/README.md
diff --git a/assessments/0008-backstage/backstage-analysis.md b/analyses/0008-backstage/backstage-analysis.md
similarity index 100%
rename from assessments/0008-backstage/backstage-analysis.md
rename to analyses/0008-backstage/backstage-analysis.md
diff --git a/assessments/0008-backstage/backstage-doc-survey.csv b/analyses/0008-backstage/backstage-doc-survey.csv
similarity index 100%
rename from assessments/0008-backstage/backstage-doc-survey.csv
rename to analyses/0008-backstage/backstage-doc-survey.csv
diff --git a/assessments/0008-backstage/backstage-glossary.md b/analyses/0008-backstage/backstage-glossary.md
similarity index 100%
rename from assessments/0008-backstage/backstage-glossary.md
rename to analyses/0008-backstage/backstage-glossary.md
diff --git a/assessments/0008-backstage/backstage-implementation.md b/analyses/0008-backstage/backstage-implementation.md
similarity index 100%
rename from assessments/0008-backstage/backstage-implementation.md
rename to analyses/0008-backstage/backstage-implementation.md
diff --git a/assessments/0008-backstage/backstage-insights-summary.md b/analyses/0008-backstage/backstage-insights-summary.md
similarity index 100%
rename from assessments/0008-backstage/backstage-insights-summary.md
rename to analyses/0008-backstage/backstage-insights-summary.md
diff --git a/assessments/0008-backstage/backstage-issues.md b/analyses/0008-backstage/backstage-issues.md
similarity index 100%
rename from assessments/0008-backstage/backstage-issues.md
rename to analyses/0008-backstage/backstage-issues.md
diff --git a/assessments/0008-backstage/user-roles.md b/analyses/0008-backstage/user-roles.md
similarity index 100%
rename from assessments/0008-backstage/user-roles.md
rename to analyses/0008-backstage/user-roles.md
diff --git a/assessments/0009-in-toto/README.md b/analyses/0009-in-toto/README.md
similarity index 100%
rename from assessments/0009-in-toto/README.md
rename to analyses/0009-in-toto/README.md
diff --git a/assessments/0009-in-toto/in-toto-analysis.md b/analyses/0009-in-toto/in-toto-analysis.md
similarity index 100%
rename from assessments/0009-in-toto/in-toto-analysis.md
rename to analyses/0009-in-toto/in-toto-analysis.md
diff --git a/assessments/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md
similarity index 100%
rename from assessments/0009-in-toto/in-toto-doc-issues.md
rename to analyses/0009-in-toto/in-toto-doc-issues.md
diff --git a/assessments/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md
similarity index 100%
rename from assessments/0009-in-toto/in-toto-implementation.md
rename to analyses/0009-in-toto/in-toto-implementation.md
diff --git a/assessments/0009-in-toto/survey-of-existing-doc.md b/analyses/0009-in-toto/survey-of-existing-doc.md
similarity index 100%
rename from assessments/0009-in-toto/survey-of-existing-doc.md
rename to analyses/0009-in-toto/survey-of-existing-doc.md
diff --git a/assessments/0010-etcd/README.md b/analyses/0010-etcd/README.md
similarity index 100%
rename from assessments/0010-etcd/README.md
rename to analyses/0010-etcd/README.md
diff --git a/assessments/0010-etcd/etcd-analysis.md b/analyses/0010-etcd/etcd-analysis.md
similarity index 100%
rename from assessments/0010-etcd/etcd-analysis.md
rename to analyses/0010-etcd/etcd-analysis.md
diff --git a/assessments/0010-etcd/etcd-implementation.md b/analyses/0010-etcd/etcd-implementation.md
similarity index 100%
rename from assessments/0010-etcd/etcd-implementation.md
rename to analyses/0010-etcd/etcd-implementation.md
diff --git a/assessments/0010-etcd/etcd-issues.md b/analyses/0010-etcd/etcd-issues.md
similarity index 100%
rename from assessments/0010-etcd/etcd-issues.md
rename to analyses/0010-etcd/etcd-issues.md
diff --git a/assessments/0011-keda/README.md b/analyses/0011-keda/README.md
similarity index 99%
rename from assessments/0011-keda/README.md
rename to analyses/0011-keda/README.md
index 8af27e7..7249fe5 100644
--- a/assessments/0011-keda/README.md
+++ b/analyses/0011-keda/README.md
@@ -2,6 +2,7 @@
title: KEDA TechDocs Analysis
tags: KEDA
---
+
- [KEDA Doc Analysis](keda-analysis.md) - Analyzes the existing KEDA documentation and provides recommendations.
- [KEDA Implementation](keda-implementation.md) - Provides detailed and actionable recommendations, intended to be worked on as GitHub issues.
- [KEDA Issues](keda-issues.md) - A list of documentation improvements derived from KEDA Implementation, entered as issues in the [kedacore/keda-docs repo](https://github.com/kedacore/keda-docs/issues/1361).
diff --git a/assessments/0011-keda/keda-analysis.md b/analyses/0011-keda/keda-analysis.md
similarity index 94%
rename from assessments/0011-keda/keda-analysis.md
rename to analyses/0011-keda/keda-analysis.md
index 3f016e6..0e616d9 100644
--- a/assessments/0011-keda/keda-analysis.md
+++ b/analyses/0011-keda/keda-analysis.md
@@ -4,27 +4,28 @@ tags: kdeda
created: 2024-02-23
modified: 2024-04-09
author: Dave Welsch (@dwelsch-esi)
+cSpell:ignore: Welsch dwelsch pastable
---
# Introduction
-This document analyzes the effectiveness and completeness of the [KEDA](https://keda.sh) 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 analyzes the effectiveness and completeness of the [KEDA](https://keda.sh) 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 step of a CNCF process aimed at assisting projects with their documentation efforts.
+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 KEDA documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. The companion document, keda-impementation.md, outlines an actionable plan for improvement.
+This document was written to analyze the current state of KEDA documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. The companion document, keda-implementation.md, outlines an actionable plan for improvement.
This document:
- Analyzes the current KEDA technical documentation and website
- Compares existing documentation against the CNCF’s standards
-- Recommends a program of key improvements with the largest return on investment. The companion document, keda-impementation.md, provides specific actionable suggestions and recommendations for overall organization and presentation of documentation
+- Recommends a program of key improvements with the largest return on investment. The companion document, keda-implementation.md, provides specific actionable suggestions and recommendations for overall organization and presentation of documentation
## Scope of analysis
-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 KEDA GitHub repository.
+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 KEDA GitHub repository.
The KEDA 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 KEDA GitHub repo.
@@ -48,7 +49,7 @@ This document is divided into three sections that represent three major areas of
Each section begins with summary ratings based on a rubric with appropriate [criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) for the section, then proceeds to:
- **Comments**: observations about the existing documentation, with a focus on how it does or does not help KEDA 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.
An accompanying document, [keda-implementation.md](./keda-implementation.md), 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]((./keda-issues.md).
@@ -63,12 +64,12 @@ Readers interested in the current state of the documentation and the reasoning b
- [Contributor documentation](#contributor-documentation)
- [Website and documentation infrastructure](#website)
-Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) specification.
+Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) specification.
### Recommendations, requirements, and best practices
-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](https://www.rfc-editor.org/rfc/rfc2119), 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](https://www.rfc-editor.org/rfc/rfc2119), 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
@@ -90,11 +91,11 @@ KEDA is a **graduated** project of CNCF. This means that the project should have
There is an overview containing **high-level conceptual** content that explains what KEDA is and how it works. The conceptual overview has one diagram, which could be more clear and align better with the text.
-Installation tasks are documented, but KEDA has other **undocumented tasks**. The documentation provides reference information for configuring KEDA but does not provide **instructions** on the most common use cases (**"happy path"**), how to use KEDA in a Kubernetes deployment.
+Installation tasks are documented, but KEDA has other **undocumented tasks**. The documentation provides reference information for configuring KEDA but does not provide **instructions** on the most common use cases (**"happy path"**), how to use KEDA in a Kubernetes deployment.
Aside from task descriptions, the documentation seems **feature complete**. Since KEDA is essentially a single-purpose API for Kubernetes, KEDA's scope is small, with the caveat that the project contains a collection of plug-in scalers (64 at the time of this writing), maintained variously by the community and by outside entities.
-Documentation is **not clearly named according to user goals**, but there is probably only one user role (persona) for KEDA – an administrator adding KEDA-based scaling to a Kubernetes deployment.
+Documentation is **not clearly named according to user goals**, but there is probably only one user role (persona) for KEDA – an administrator adding KEDA-based scaling to a Kubernetes deployment.
There are **escalation paths** available:
- The documentation contains a Troubleshooting section.
@@ -115,7 +116,7 @@ There is partial **getting started** information in the documentation as [Deploy
There are **getting started** pages on the main GitHub repo for the following supported systems:
- RabbitMQ and Go
- Azure Functions and Queues
-- Azure Functions and Kafka on Openshift 4
+- Azure Functions and Kafka on OpenShift 4
- Azure Storage Queue with ScaledJob
These pages list installing KEDA as a prerequisite. Taken together, "Deploying KEDA" and the scenarios in the repo make a complete Getting Started workflow, but they are in two separate places and the scenarios are not findable from the website.
@@ -169,7 +170,7 @@ Reorganize the Table of Contents. Rename "The KEDA Documentation"; the name is m
- Rename "Operate" to "Operator Guide".
- Move "Troubleshooting" to the end of the User Guide.
-Move the scenarios from the KEDA GitHub repo to the user documentation on the website. Link to these from the end of "Deploying KEDA" to create a workflow for new users.
+Move the scenarios from the KEDA GitHub repo to the user documentation on the website. Link to these from the end of "Deploying KEDA" to create a workflow for new users.
Write step-by-step tasks in the User Guide that explain how to run and use KEDA, or link to other documentation that does, for example the [Kubernetes documentation on HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). For example, explain how to do 0-to-1 scaling.
@@ -183,9 +184,9 @@ No recommendations
### Content creation processes
-Make it easier to find the instructions for releasing a new version of the documentation and updating the documentation.
+Make it easier to find the instructions for releasing a new version of the documentation and updating the documentation.
-Document in the repo who the website/documentation maintainers are.
+Document in the repo who the website/documentation maintainers are.
### Inclusive language
@@ -197,23 +198,23 @@ Remove non-inclusive language throughout the documentation as recommended on the
KEDA 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) |
-| --- | --- |
-| Communication methods documented | 3 - meets standards |
+| --- | --- |
+| 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 |
+| “New contributor” getting started content | 3 - meets standards |
+| Project governance documentation | 4 - meets or exceeds standards |
## Comments
### Communication methods documented
-The KEDA main repo points to **community** resources, including a KEDA Slack channel in the Kubernetes workspace. There is a **community page** on the website that invites readers to a **biweekly Zoom meeting**. The main website has direct links in the footer to the Slack community, the **GitHub** repo, and a Twitter feed. I could not find any mention of a **mailing list**.
+The KEDA main repo points to **community** resources, including a KEDA Slack channel in the Kubernetes workspace. There is a **community page** on the website that invites readers to a **biweekly Zoom meeting**. The main website has direct links in the footer to the Slack community, the **GitHub** repo, and a Twitter feed. I could not find any mention of a **mailing list**.
### Beginner friendly issue backlog
-Doc **issues** in the repo are **well documented** and have been labeled and, presumably, **triaged**.
+Doc **issues** in the repo are **well documented** and have been labeled and, presumably, **triaged**.
There is a **good first issue** label (although this label is not currently applied to any issues).
@@ -222,9 +223,9 @@ There are **stale issues**, but they seem for the most part to be managed. There
### New contributor getting started content
-The website contains a **community section**.
+The website contains a **community section**.
-There is **CONTRIBUTORS** document in the website/documentation repo with instructions for **getting help** and building and contributing new documentation.
+There is **CONTRIBUTORS** document in the website/documentation repo with instructions for **getting help** and building and contributing new documentation.
### Project governance documentation
@@ -258,8 +259,8 @@ No recommendations.
KEDA 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) |
-| --- | --- |
+| Criterion | Rating (1-5) |
+| --- | --- |
| Single-source for all files | 3 - meets standards |
| Meets min website req. (for maturity level) | 2 - needs improvement |
| Usability, accessibility, and design | 3 - meets standards |
@@ -282,7 +283,7 @@ KEDA is a **graduated** project of CNCF. This means that the project should have
Source files for all website pages reside in a **single repo**. However, some user documentation pages (speciifically, "Getting started" topics linked from the main (kedacore/keda) repo) would better serve users if they were moved to the tech docs on the website.
-Website files are all in the website repo.
+Website files are all in the website repo.
### Minimal website requirements
@@ -357,7 +358,7 @@ There is a substantial **logo wall of users and participating organizations**. T
### Maintenance planning
-The website uses Hugo and Docsy, which are the recommended **website tooling** for CNCF projects.
+The website uses Hugo and Docsy, which are the recommended **website tooling** for CNCF projects.
There is no sign that the project is **cultivating website maintainers** from the community. However, the site is small and much of the content is links to community or third-party scalers (plugin components).
diff --git a/assessments/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md
similarity index 96%
rename from assessments/0011-keda/keda-implementation.md
rename to analyses/0011-keda/keda-implementation.md
index b142fc6..7b777fa 100644
--- a/assessments/0011-keda/keda-implementation.md
+++ b/analyses/0011-keda/keda-implementation.md
@@ -5,13 +5,13 @@ tags: keda
# Introduction
-This document provides actionable suggestions for improving the KEDA technical documentaiton.
+This document provides actionable suggestions for improving the KEDA technical documentaiton.
For an analysis and general discussion of recommendations on KEDA technical documentation, see [keda-analysis.md][keda-analysis].
## Recommendations, requirements, and best practices
-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.
+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 documentation recommendations for this project are:
- [Reorganize the table of contents (TOC)](#reorganize-the-table-of-contents-toc)
@@ -29,12 +29,12 @@ The documentation recommendations for this project are:
Reorganize the Table of Contents to:
- Better welcome and orient new users
-- Separate user rules (personas), if there are more than one
+- Separate user rules (personas), if there are more than one
- Improve findability and access to tasks and procedures
- Separate conceptual, task, and reference information
In general, follow these principles when reorganizing the documentation:
-- Put architecture, operating principles, and other conceptual explanations in the technical overview.
+- Put architecture, operating principles, and other conceptual explanations in the technical overview.
- Write instructions (in "Using KEDA" and "Getting Started") as step-by-step procedures. Title each procedure using "-ing" verbs; for example "Integrating", "Using", "Migrating".
- Put purely reference information in the Reference section. Link to this information where relevant from the procedures in the "Using KEDA" and "Getting Started" sections.
- Separate and/or label information, especially tasks, by which user role it pertains to (again, if more than one).
@@ -107,7 +107,7 @@ Here is a proposed outline for the tech doc Table of Contents:
- ...
- [FAQ](/docs/2.13/faq/)
- Glossary
-- [Scalers](/docs/2.13/scalers/)
+- [Scalers](/docs/2.13/scalers/)
- [ActiveMQ](/docs/2.13/scalers/activemq/)
- ...
- [Solr](/docs/2.13/scalers/solr/)
@@ -128,18 +128,18 @@ Create a glossary of terms specific to KEDA. Add to the Reference section.
# Add "How to set up a scaler" to the Operator guide
-Setting up a scaler seems to be largely a matter of installing the scaler and providing parameters in a configuration file. While the configurations are provided for all the various scalers, there doesn't seem to be a description of the procedure for doing the basic setup. This should go at the top of the Operator guide. Users should be able to follow the procedure for any (or at least most) scalers.
+Setting up a scaler seems to be largely a matter of installing the scaler and providing parameters in a configuration file. While the configurations are provided for all the various scalers, there doesn't seem to be a description of the procedure for doing the basic setup. This should go at the top of the Operator guide. Users should be able to follow the procedure for any (or at least most) scalers.
Any scaler that requires special instructions other than the configuration file should have its own procedure page, listing the extra steps required.
# Write a New User workflow
-Write a task-based, step-by-step workflow for new users. Assume the new user has no experience with KEDA and is fairly new to Kubernetes.
+Write a task-based, step-by-step workflow for new users. Assume the new user has no experience with KEDA and is fairly new to Kubernetes.
The current documentation assumes that users know how to deploy and use Kubernetes Custom Resources, and that using KEDA is a matter of knowing the right configuration parameters and deploying the right resources. This might be true for veteran users, but new users want explicit, foolproof instructions. The following outline, extracted from the proposed outline in [Reorganize the Table of Contents](#reorganize-the-table-of-contents), has been annotated to illustrate this point:
* [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA Documentation" heading) *Make the new user entry point obvious*
- * [Deploying KEDA](/docs/2.13/deploy/) *This is analagous to "Install" for application software or a plugin. It's the starting point for a new user.*
+ * [Deploying KEDA](/docs/2.13/deploy/) *This is analogous to "Install" for application software or a plugin. It's the starting point for a new user.*
* [Prerequisites](https://keda.sh/docs/2.13/operate/cluster/#requirements) *Make sure the new user has their tools gathered up before they start. This reduces frustration. Next, what is the advantage of one deployment method over another? If the choice is not completely arbitrary, explain the differences here to help the new user decide. Also, if prerequisites depend on the deployment type, you can optionally put a Prerequisites section in each deployment procedure rather than here.*
* [Deploying with Helm](#helm)
- [Installing](#install)
@@ -153,14 +153,14 @@ The current documentation assumes that users know how to deploy and use Kubernet
* [Deploying KEDA on MicroK8s](#microk8s)
- [Installing](#install-3)
- [Uninstalling](#uninstall-3)
- * Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like https://github.com/kedacore/sample-hello-world-azure-functions) *Analagous to a "Hello World" exercise in programming language or API guides*
+ * Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like https://github.com/kedacore/sample-hello-world-azure-functions) *analogous to a "Hello World" exercise in programming language or API guides*
# Update the doc content creation instructions
In the keda-docs [README](https://github.com/kedacore/keda-docs/blob/main/README.md):
-- Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial offering!" sections into their own files, or move them to the bottom of the README, so they're not at the top of the keda-docs README.
-- Combine "Adding scaler documentation" and "Writing documentation for a scaler" so that they're not separated by "Writing documentation for a new authentication provider".
+- Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial offering!" sections into their own files, or move them to the bottom of the README, so they're not at the top of the keda-docs README.
+- Combine "Adding scaler documentation" and "Writing documentation for a scaler" so that they're not separated by "Writing documentation for a new authentication provider".
Document in the repo (keda-docs, keda, or both) who the website/documentation maintainers are.
@@ -170,14 +170,14 @@ Remove non-inclusive language throughout the documentation as recommended by the
# Make user roles explicit
-KEDA seems to have only one explicit user role (or *persona*), namely, an Operator using KEDA to scale resources on a Kubernetes installation. Regardless, this user role should be explicitly distinguished from the project Contributor user role. Use cases are different between the two roles. One strategy for separating the documentation is to confine the Contributor docs to the GitHub repo.
+KEDA seems to have only one explicit user role (or *persona*), namely, an Operator using KEDA to scale resources on a Kubernetes installation. Regardless, this user role should be explicitly distinguished from the project Contributor user role. Use cases are different between the two roles. One strategy for separating the documentation is to confine the Contributor docs to the GitHub repo.
The definition of the Operator role could be as minimal as a "who should use this documentation" paragraph in the product introduction.
# Clarify documentation maintainers
-Create an `OWNERS.md` file to document (on the repo) the current custodian(s) of the following accounts: analytics (GA4), site-search (Algolia).
+Create an `OWNERS.md` file to document (on the repo) the current custodian(s) of the following accounts: analytics (GA4), site-search (Algolia).
Explicitly list and solicit maintainers and contributors for documentation, either in the new OWNERS file or the governance MAINTAINERS file.
diff --git a/assessments/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md
similarity index 96%
rename from assessments/0011-keda/keda-issues.md
rename to analyses/0011-keda/keda-issues.md
index 1a08b85..95673c8 100644
--- a/assessments/0011-keda/keda-issues.md
+++ b/analyses/0011-keda/keda-issues.md
@@ -1,6 +1,7 @@
---
title: KEDA Umbrella Issue
tags: keda
+cSpell:ignore: findability
---
# Overview
@@ -12,7 +13,7 @@ This document outlines the recommended changes to the KEDA documentation. The fo
Reorganize the Table of Contents to:
- Better welcome and orient new users
-- Separate user roles (personas), if there are more than one
+- Separate user roles (personas), if there are more than one
- Improve findability and access to tasks and procedures
- Separate conceptual, task, and reference information
@@ -27,9 +28,9 @@ Here is a proposed high-level outline for the tech doc Table of Contents. Work o
## Issue: Reorganize Concepts
-Remove everything that's not a conceptual overview.
+Remove everything that's not a conceptual overview.
-Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point.
+Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point.
- [KEDA Concepts](https://keda.sh/docs/2.13/concepts/)
- What is KEDA?
@@ -50,12 +51,12 @@ Here is a proposed outline. Links are to existing pages that can be used as-is o
Write a task-based, step-by-step workflow for new users. Start with the current "KEDA Documentation" section.
-Assume the new user has no experience with KEDA and is fairly new to Kubernetes. The current documentation assumes that users know how to deploy and use Kubernetes Custom Resources, and that using KEDA is a matter of knowing the right configuration parameters and deploying the right resources. This might be true for veteran users, but new users want explicit, foolproof instructions.
+Assume the new user has no experience with KEDA and is fairly new to Kubernetes. The current documentation assumes that users know how to deploy and use Kubernetes Custom Resources, and that using KEDA is a matter of knowing the right configuration parameters and deploying the right resources. This might be true for veteran users, but new users want explicit, foolproof instructions.
The following outline has been annotated to illustrate this point. Links are to existing pages that can be used as-is or provide a starting point. Pages with multiple procedures (for example, the "Deploying KEDA" page) should be split into multiple pages, one for each procedure.
- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA Documentation" heading) *Make the new user entry point obvious.*
- - [Deploying KEDA](/docs/2.13/deploy/) *This is analagous to "Install" for application software or a plugin. It's the starting point for a new user.*
+ - [Deploying KEDA](/docs/2.13/deploy/) *This is analogous to "Install" for application software or a plugin. It's the starting point for a new user.*
- Overview *Briefly explain the differences between installation methods. What is the advantage of one deployment method over another? If the choice is not completely arbitrary, explain the differences here to help the new user decide.*
- [Prerequisites](https://keda.sh/docs/2.13/operate/cluster/#requirements) *Make sure the new user has their tools gathered up before they start. This reduces frustration. Also, if prerequisites depend on the deployment type, you can optionally put a Prerequisites section in each deployment procedure rather than here.*
- [Deploying with Helm](#helm)
@@ -70,7 +71,7 @@ The following outline has been annotated to illustrate this point. Links are to
- [Deploying KEDA on MicroK8s](#microk8s)
- [Installing](#install-3)
- [Uninstalling](#uninstall-3)
- - Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like https://github.com/kedacore/sample-hello-world-azure-functions) *Analagous to a "Hello World" exercise in programming language or API guides*
+ - Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like https://github.com/kedacore/sample-hello-world-azure-functions) *analogous to a "Hello World" exercise in programming language or API guides*
## Issue: Update the Operator Guide
@@ -86,7 +87,7 @@ Some guidelines:
- https://keda.sh/docs/2.13/operate/cluster/#firewall
- Break up long pages containing several topics. Aim for one major topic per page. For example, all HTTP-related headings on the [Cluster](https://keda.sh/docs/2.13/operate/cluster/) page could go on one page named "Using HTTP".
-Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point.
+Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point.
- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename current "Operate")
- Setting up a scaler (write or adapt a more detailed procedure than the example used in Getting Started - see ["Write 'Setting Up a Scaler'"](#write-setting-up-a-scaler))
@@ -116,14 +117,14 @@ Here is a proposed outline. Links are to existing pages that can be used as-is o
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/, /docs/2.13/troubleshooting/)
-## Issue: Create a "Reference" topic
+## Issue: Create a "Reference" topic
- The Reference section should be at or near the end of the ToC
- Include the following information in the Reference section:
- Move the FAQ to the Reference section.
- Add a glossary to the Reference section.
-Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point.
+Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point.
- Reference
- [Authentication Providers](https://keda.sh/docs/2.13/authentication-providers/)
@@ -141,11 +142,11 @@ Here is a proposed outline. Links are to existing pages that can be used as-is o
# Separate reference and task information
-A common practice that reduces documentation effectiveness is mixing conceptual and task information. *Conceptual* discussion can be thought of as *How it works*; a *Task* is *How you use it*. Tasks should be described step-by-step as explicitly as possible.
+A common practice that reduces documentation effectiveness is mixing conceptual and task information. *Conceptual* discussion can be thought of as *How it works*; a *Task* is *How you use it*. Tasks should be described step-by-step as explicitly as possible.
Reference information is also embedded sometimes, but in general is easy to extract.
-In pages where conceptual, reference, and/or task info appears on the same page, separate and move each to the appropriate section.
+In pages where conceptual, reference, and/or task info appears on the same page, separate and move each to the appropriate section.
Here is a list of some of the KEDA pages containing more than one type of information. Some of these pages might appear in other issues suggesting that they be revised or relocated. If this creates contradictory recommendations, some judgement might be required to rearrange things.
@@ -192,14 +193,14 @@ For an example from another CNCF project, see the [glossary in the Backstage doc
# Write "Setting Up a Scaler"
-Setting up a scaler seems to be largely a matter of installing the scaler and providing parameters in a configuration file. While the configurations are provided for all the various scalers, there doesn't seem to be a description of the procedure for doing the basic setup. This should go at the top of the Operator guide.
+Setting up a scaler seems to be largely a matter of installing the scaler and providing parameters in a configuration file. While the configurations are provided for all the various scalers, there doesn't seem to be a description of the procedure for doing the basic setup. This should go at the top of the Operator guide.
Users should be able to follow the procedure for any (or at least most) scalers. Any scaler that requires special instructions other than the configuration file should have its own procedure page, listing the extra steps required.
# Make user roles explicit
-KEDA seems to have only one explicit user role (or *persona*), namely, an Operator using KEDA to scale resources on a Kubernetes installation. Regardless, this user role should be explicitly distinguished from the project Contributor user role. Use cases are different between the two roles. One strategy for separating the documentation is to confine the Contributor docs to the GitHub repo.
+KEDA seems to have only one explicit user role (or *persona*), namely, an Operator using KEDA to scale resources on a Kubernetes installation. Regardless, this user role should be explicitly distinguished from the project Contributor user role. Use cases are different between the two roles. One strategy for separating the documentation is to confine the Contributor docs to the GitHub repo.
The definition of the Operator role could be as minimal as a "who should use this documentation" paragraph in the product introduction.
@@ -209,13 +210,13 @@ The definition of the Operator role could be as minimal as a "who should use thi
Make the following changes to improve the effectiveness of the KEDA documentation contributor instructions.
In the keda-docs [README](https://github.com/kedacore/keda-docs/blob/main/README.md):
-- Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial offering!" sections into their own files, or move them to the bottom of the README, so they're not at the top of the keda-docs README.
-- Combine "Adding scaler documentation" and "Writing documentation for a scaler" so that they're not separated by "Writing documentation for a new authentication provider".
+- Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial offering!" sections into their own files, or move them to the bottom of the README, so they're not at the top of the keda-docs README.
+- Combine "Adding scaler documentation" and "Writing documentation for a scaler" so that they're not separated by "Writing documentation for a new authentication provider".
# Clarify the KEDA website and documentation maintainers
-Create an `OWNERS.md` file to document (on the kedacore/keda-docs repo) the current custodian(s) of the following accounts: analytics (GA4), site-search (Algolia).
+Create an `OWNERS.md` file to document (on the kedacore/keda-docs repo) the current custodian(s) of the following accounts: analytics (GA4), site-search (Algolia).
Explicitly document in the repo (keda-docs, keda, or both) who the website/documentation maintainers are. Solicit maintainers and contributors for documentation, either in the new OWNERS file or the governance MAINTAINERS file.
diff --git a/assessments/README.md b/analyses/README.md
similarity index 98%
rename from assessments/README.md
rename to analyses/README.md
index 84034f2..7c48309 100644
--- a/assessments/README.md
+++ b/analyses/README.md
@@ -1,3 +1,5 @@
+
+
# CNCF TechDocs Analysis for OSS Projects
## Purpose
@@ -22,7 +24,7 @@ The analyses also provide information of value to organizations with an interest
## Contents
-This directory contains completed analyses of the technical documentation for selected CNCF incubating and graduated software projects.
+This directory contains completed analyses of the technical documentation for selected CNCF incubating and graduated software projects.
The analyses are in one of two formats depending on when they were written. Earlier analyses (**0001** - **0007**) are Markdown files, each of which is the sole artifact of the analysis.
diff --git a/docs/analytics.md b/docs/analytics.md
index 641200c..8cae4c0 100644
--- a/docs/analytics.md
+++ b/docs/analytics.md
@@ -135,8 +135,6 @@ Follow these steps:
-- provided that there are active users. You should see roughly the same
number and distribution of active users reported by the UA console.
-
-
### Stage 2 - configure the GA4 ID as the main analytics ID
GA4 only works when your project's website is configured using the [gtag.js][]
@@ -198,6 +196,6 @@ that your project is using.
[issue #108]: https://github.com/cncf/techdocs/issues/108
[migration-help]: https://support.google.com/analytics/answer/10759417
[opentelemetry.io/layouts/partials/google-analytics.html]: https://github.com/open-telemetry/opentelemetry.io/blob/3d8a59ea508b46497500297f334a079a4f91e293/layouts/partials/google-analytics.html
-[stage 2]: #stage-2
+[stage 2]: #stage-2---configure-the-ga4-id-as-the-main-analytics-id
[status table]: https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA
[ua]: https://support.google.com/analytics/answer/11583528
diff --git a/assistance.md b/docs/assistance.md
similarity index 96%
rename from assistance.md
rename to docs/assistance.md
index 41f7fac..d11fe5c 100644
--- a/assistance.md
+++ b/docs/assistance.md
@@ -2,7 +2,7 @@
This document outlines the Cloud Native Computing Foundation (CNCF) Technical Documentation Assistance Program (the Program), a service offered by CNCF Tech Docs for evaluating and improving an OSS project's technical documentation. The process is designed to:
-1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](docs/analysis/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level.
+1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](analysis/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level.
1. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project.
1. Expand on the recommended changes in an implementation plan.
1. Break down the implementation into a documentation project backlog comprising a GitHub Issues list.
diff --git a/docs/searching-documentation.md b/docs/searching-documentation.md
index c680b84..9591a4c 100644
--- a/docs/searching-documentation.md
+++ b/docs/searching-documentation.md
@@ -1,28 +1,16 @@
# Documentation Search
This page describes some common alternatives for static site search.
-* [Lunr](#lunr)
* [Google search](#programmable-search-engine-by-google)
* [Docsearch by Algolia](#docsearch-by-algolia)
-
-# Docsearch by Algolia
-[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the Algolia search engine that crawls your docs and provides a dropdown search experience on your website.
-
-## Pros
-- Provides Front-end widgets out of the box: search input, dynamic positioning of search results, etc.
-- Integrations with popular frameworks
-- Support for multi-language search.
-
-## Cons
-- Not entirely free- Limited to 10k records
-- Limited access to features.
+* [Lunr](#lunr)
-# Programmable Search Engine by Google
+## Programmable Search Engine by Google
[Google’s programmable search engine](https://developers.google.com/custom-search/docs/overview) is a search tool that crawls your **live site** and renders results on your website.
-## Pros
+### Pros
- Easy to configure and setup
- Multi-language support
- Support for image search
@@ -30,14 +18,28 @@ This page describes some common alternatives for static site search.
- No daily limits for queries or records.
-## Cons
+### Cons
- Search index is completely managed and hosted on Google servers.
-# Lunr
+
+## Docsearch by Algolia
+[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the Algolia search engine that crawls your docs and provides a dropdown search experience on your website.
+
+### Pros
+- Provides Front-end widgets out of the box: search input, dynamic positioning of search results, etc.
+- Integrations with popular frameworks
+- Support for multi-language search.
+
+### Cons
+- Not entirely free- Limited to 10k records
+- Limited access to features.
+
+
+## Lunr
[Lunr.js](https://lunrjs.com/) is a small, full-text search library for use in the browser. Lunr enables you to provide a great search experience without needing external, server-side, search services.
-## Pros
+### Pros
- Support for offline search
- No external package dependency
- Completely free and open source
@@ -46,11 +48,11 @@ This page describes some common alternatives for static site search.
- Search index is completely managed and hosted by the owner.
-## Cons
+### Cons
- Can be complex to configure and setup (If a team is already using hugo/docsy, this should be *very* easy to setup).
- Depending on site setup, may require javascript knowledge
-# When Is It Best To Use One Over Another?
-If you are looking to create a search capability for your open source project without having to depend on a 3rd party service, then you should consider using [Lunr](https://lunrjs.com/). You can take a look at [this custom implementation](https://github.com/vitessio/website/pull/1119) or [Hugo/Docsy implementation](https://github.com/etcd-io/website/pull/403) to see the different ways we used Lunr to implement search.
+## When Is It Best To Use One Over Another?
+If you are looking to create a search capability for your open source project without having to depend on a 3rd party service, then you should consider using [Lunr](https://lunrjs.com/). You can take a look at [this custom implementation](https://github.com/vitessio/website/pull/1119) or [Hugo/Docsy implementation](https://github.com/etcd-io/website/pull/403) to see the different ways we used Lunr to implement search.
If you are looking to create a search engine that not only focuses on the contents of one website (site search), but on a particular topic from multiple sites, then you should consider the [Programmable Search Engine (Google search)](https://developers.google.com/custom-search/docs/overview).
diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md
index ce0a6b6..484fb4c 100644
--- a/docs/versioning-documentation.md
+++ b/docs/versioning-documentation.md
@@ -120,7 +120,7 @@ The subdomain scheme uses some simpler template code to generate links, only hav
Each version of the documentation is its own site
- Uses git feature branches rather than folders to organize versions
- Separate site in Netlify for each version supported
-- Simpler template code, more complex config
+- Simpler template code, more complex config
Scores high on:
- Localization / Internationalization
@@ -146,7 +146,7 @@ Pursley et al. (2020, L4-L9)[4](#footnote4)
The dropdown example is made simpler because the config is more complex and because the server setup is more complex.
-https://kubernetes.io `website/config.toml`
+https://kubernetes.io `website/config.toml`
```toml
[[params.versions]]
fullversion = "v1.20.0"
@@ -184,14 +184,14 @@ For small to medium sized sites using one language/location, a folder based meth
1: [Bannister, T.](https://github.com/sftim) et al. (2020, December 23). kubernetes/website. GitHub. Retrieved February 2, 2021 from [https://github.com/kubernetes/website/blob/ 7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml](https://github.com/kubernetes/website/blob/7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml)
-2: [Batard, T.](https://github.com/tbatard) (2020, August 13). _vmware-tanzu/velero_. GitHub. Retrieved January 19, 2021 from [https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html](https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html)
+2: [Batard, T.](https://github.com/tbatard) (2020, August 13). _vmware-tanzu/velero_. GitHub. Retrieved January 19, 2021 from [https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html](https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html)
- 3: [Brubaker, N.](https://github.com/nrb), [Rosland, J.](https://github.com/jonasrosland), [Thompson, C.](https://github.com/carlisia), [Batard, T.](https://github.com/tbatard) (2020, September 16). _vmware-tanzu/velero_. GitHub. Retrieved February 2, 2021 from [https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml](https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml)
+ 3: [Brubaker, N.](https://github.com/nrb), [Rosland, J.](https://github.com/jonasrosland), [Thompson, C.](https://github.com/carlisia), [Batard, T.](https://github.com/tbatard) (2020, September 16). _vmware-tanzu/velero_. GitHub. Retrieved February 2, 2021 from [https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml](https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml)
- 4: [Pursley, B.](https://github.com/brianpursley), [Horgan, C.](https://github.com/celestehorgan), [Takahashi, S.](https://github.com/shuuj3) (2020, July 21). _kubernetes/website_. GitHub. Retrieved February 2, 2021 from [https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html](https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html)
+ 4: [Pursley, B.](https://github.com/brianpursley), [Horgan, C.](https://github.com/celestehorgan), Takahashi, S. (2020, July 21). _kubernetes/website_. GitHub. Retrieved February 2, 2021 from [https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html](https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html)
---
-This page has been adapted from the [Technical Documentation Versioning slide show](https://technical-documentation-versioning.netlify.app/), its source can be found here: [https://github.com/nate-double-u/technical-documentation-versioning](https://github.com/nate-double-u/technical-documentation-versioning).
+This page has been adapted from the [Technical Documentation Versioning slide show](https://technical-documentation-versioning.netlify.app/), its source can be found here: [https://github.com/nate-double-u/technical-documentation-versioning](https://github.com/nate-double-u/technical-documentation-versioning).
diff --git a/package.json b/package.json
index e5f92db..92c7942 100644
--- a/package.json
+++ b/package.json
@@ -8,8 +8,8 @@
"_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'",
"_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'",
"check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
- "check:links": "npx markdown-link-check --config .markdown-link-check.json *.md",
- "check:spelling": "npx cspell --no-progress -c .cspell.yml .",
+ "check:links": "bash -c 'for f in *.md docs/*.md; do npx markdown-link-check --config .markdown-link-check.json $f || exit 1; done'",
+ "check:spelling": "npx cspell --no-progress -c .cspell.yml *.md",
"check": "npm run seq -- $(npm run -s _list:check:*)",
"fix:format": "npm run _check:format -- --write",
"fix": "npm run seq -- $(npm -s run _list:fix:*)",