From bb1228f19f9c856c5011c69cf233b16830bfbacf Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 26 Feb 2025 15:21:18 -0500 Subject: [PATCH] [chore] Check Keda analysis pages Signed-off-by: Patrice Chalin --- analyses/0011-keda/keda-analysis.md | 24 ++++++----- analyses/0011-keda/keda-implementation.md | 31 +++++++------- analyses/0011-keda/keda-issues.md | 49 ++++++++++++----------- package.json | 2 +- 4 files changed, 55 insertions(+), 51 deletions(-) diff --git a/analyses/0011-keda/keda-analysis.md b/analyses/0011-keda/keda-analysis.md index 147b404..adcaf5e 100644 --- a/analyses/0011-keda/keda-analysis.md +++ b/analyses/0011-keda/keda-analysis.md @@ -6,6 +6,8 @@ author: Dave Welsch (@dwelsch-esi) cSpell:ignore: Welsch dwelsch pastable servicedesk --- + + # Introduction This document analyzes the effectiveness and completeness of the @@ -46,15 +48,15 @@ Netlify platform. The site's code is stored on the KEDA GitHub repo. **In scope:** -- Website: https://keda.sh -- Documentation: https://keda.sh/docs -- Website repo: https://github.com/kedacore/keda-docs -- Governance repo: https://github.com/kedacore/governance -- Main project contributor info: https://github.com/kedacore/keda +- Website: +- Documentation: +- Website repo: +- Governance repo: +- Main project contributor info: **Out of scope:** -- Other KEDA repos: https://github.com/kedacore/* +- Other KEDA repos under ## How this document is organized @@ -233,12 +235,12 @@ The documentation includes some examples of [**non-inclusive language**](https://inclusivenaming.org/). For example: - "easily", "simple", "simply", etc. - - https://keda.sh/docs/2.13/deploy/ - - https://keda.sh/docs/2.13/deploy/#uninstall-3 - - https://keda.sh/docs/2.13/concepts/scaling-deployments/#triggers + - + - + - - "master" node - - https://keda.sh/docs/2.13/troubleshooting/#google-kubernetes-engine-gke - - https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/#authentication-parameters + - + - ## Recommendations diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index ac0ec34..134fc01 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -1,8 +1,9 @@ --- title: Implementing KEDA Doc Improvements -tags: keda --- + + # Introduction This document provides actionable suggestions for improving the KEDA technical @@ -76,7 +77,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename current "KEDA Documentation" heading) - [Deploying KEDA](https://keda.sh/docs/2.13/deploy/) - - Prerequisites (https://keda.sh/docs/2.13/operate/cluster/#requirements) + - Prerequisites () - [Deploying with Helm](?no-link-check#helm) - [Installing](?no-link-check#install) - [Uninstalling](?no-link-check#uninstall) @@ -91,7 +92,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [Uninstalling](?no-link-check#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) + ) - [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename current "Operate") - How to set up a scaler (a more detailed procedure than the example used in @@ -102,13 +103,13 @@ Here is a proposed outline for the tech doc Table of Contents: - ... and so on. - [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/) - Prevention Rules - (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules) + () - Validation Enforcement - [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - Except sections that are purely reference info, for example: - - https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility - - https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity - - https://keda.sh/docs/2.13/operate/cluster/#firewall + - + - + - - [Integrating with OpenTelemetry Collector (Experimental)](https://keda.sh/docs/2.13/integrations/opentelemetry/) - [Integrating with Prometheus](https://keda.sh/docs/2.13/integrations/prometheus/) - [Using the KEDA Metrics Server](https://keda.sh/docs/2.13/operate/metrics-server/) @@ -118,22 +119,22 @@ Here is a proposed outline for the tech doc Table of Contents: - [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current "Migration Guide") - Caching Metrics - (https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics) + () - Pausing Autoscaling of deployments - (https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling) + () - Pausing Autoscaling of jobs - (https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling) - - [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/, - /docs/2.13/troubleshooting/) + () + - [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/), + `/docs/2.13/troubleshooting/` - Reference - [Authentication Providers](https://keda.sh/docs/2.13/authentication-providers/) - [AWS (IRSA) Pod Identity Webhook](https://keda.sh/docs/2.13/authentication-providers/aws/) - ... - [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/) - Scaled Object specification (from "Concepts"; - https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec) + ) - ScaledJob specification - (https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec) + () - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... @@ -210,7 +211,7 @@ annotated to illustrate this point: - [Uninstalling](?no-link-check#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) _analogous + ) _analogous to a "Hello World" exercise in programming language or API guides_ # Update the doc content creation instructions diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index 31925b5..f633ae0 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -1,9 +1,10 @@ --- title: KEDA Umbrella Issue -tags: keda cSpell:ignore: externalscaler findability --- + + # Overview This document outlines the recommended changes to the KEDA documentation. The @@ -98,7 +99,7 @@ into multiple pages, one for each procedure. - [Uninstalling](?no-link-check#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) _analogous + ) _analogous to a "Hello World" exercise in programming language or API guides_ ## Issue: Update the Operator Guide @@ -110,9 +111,9 @@ Some guidelines: - Move "Troubleshooting" to the end of the Operator Guide. - Relocate sections that are purely reference information, including these sections in [Cluster](https://keda.sh/docs/2.13/operate/cluster/): - - https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility - - https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity - - 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 @@ -132,7 +133,7 @@ or provide a starting point. - ... and so on. - [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/) - Prevention Rules - (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules) + () - Validation Enforcement - [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - (Relocate sections that are purely reference info) @@ -150,13 +151,13 @@ or provide a starting point. - [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current "Migration Guide") - Caching Metrics - (https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics) + () - Pausing Autoscaling of deployments - (https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling) + () - Pausing Autoscaling of jobs - (https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling) - - [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/, - /docs/2.13/troubleshooting/) + () + - [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/) + `/docs/2.13/troubleshooting/` ## Issue: Create a "Reference" topic @@ -174,9 +175,9 @@ or provide a starting point. - ... - [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/) - Scaled Object specification (from "Concepts"; - https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec) + ) - ScaledJob specification - (https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec) + () - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... @@ -201,17 +202,17 @@ 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. -| Page Title | URL | Notes | -| ------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Deploying KEDA | https://keda.sh/docs/2.13/deploy/ | Page is all install and uninstall tasks, but put each install procedure on its own page. Make this page an intro and index. | -| Scaling Deployments, StatefulSets and Custom Resources | https://keda.sh/docs/2.13/concepts/scaling-deployments/ | The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task. | -| Scaling Jobs | https://keda.sh/docs/2.13/concepts/scaling-jobs/ | "ScaledJob spec" is reference information. | -| Authentication | https://keda.sh/docs/2.13/concepts/authentication/ | Deliberately discuss the three patterns listed at the top of the page. This entire page might be better written as a task-based how-to guide. | -| External Scalers | https://keda.sh/docs/2.13/concepts/external-scalers/ | "Implementing KEDA external scaler GRPC interface" is a series of tasks. The steps after the first 2 are choices -- Describe the task of downloading `externalscaler.proto` and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently. | -| Troubleshooting | https://keda.sh/docs/2.13/concepts/troubleshooting/ | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". | -| Cluster | https://keda.sh/docs/2.13/operate/cluster/ | See the "Update the Operator Guide" issue | -| Events | https://keda.sh/docs/2.13/operate/events/ | This is reference information. | -| Integrate with Prometheus | https://keda.sh/docs/2.13/integrations/prometheus/ | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". | +| Page Title | URL | Notes | +| ------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Deploying KEDA | | Page is all install and uninstall tasks, but put each install procedure on its own page. Make this page an intro and index. | +| Scaling Deployments, StatefulSets and Custom Resources | | The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task. | +| Scaling Jobs | | "ScaledJob spec" is reference information. | +| Authentication | | Deliberately discuss the three patterns listed at the top of the page. This entire page might be better written as a task-based how-to guide. | +| External Scalers | | "Implementing KEDA external scaler GRPC interface" is a series of tasks. The steps after the first 2 are choices -- Describe the task of downloading `externalscaler.proto` and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently. | +| Troubleshooting | | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". | +| Cluster | | See the "Update the Operator Guide" issue | +| Events | | This is reference information. | +| Integrate with Prometheus | | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". | # Write a Glossary diff --git a/package.json b/package.json index 58206f8..1bf1be2 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", "_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'", "_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path '*/00*'", - "_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010|/0011'", + "_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010'", "_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)",