Skip to content

[chore] Check Keda analysis pages #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nate-double-u merged 1 commit into from
Feb 26, 2025
Merged

[chore] Check Keda analysis pages #297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions analyses/0011-keda/keda-analysis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: Welsch dwelsch pastable servicedesk
---

<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->

# Introduction

This document analyzes the effectiveness and completeness of the
Expand Down Expand Up @@ -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: <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>

**Out of scope:**

- Other KEDA repos: https://github.com/kedacore/*
- Other KEDA repos under <https://github.com/kedacore/>

## How this document is organized

Expand Down Expand Up @@ -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
- <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
- <https://keda.sh/docs/2.13/troubleshooting/#google-kubernetes-engine-gke>
- <https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/#authentication-parameters>

## Recommendations

Expand Down
31 changes: 16 additions & 15 deletions analyses/0011-keda/keda-implementation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
title: Implementing KEDA Doc Improvements
tags: keda
---

<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->

# Introduction

This document provides actionable suggestions for improving the KEDA technical
Expand Down Expand Up @@ -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 (<https://keda.sh/docs/2.13/operate/cluster/#requirements>)
- [Deploying with Helm](?no-link-check#helm)
- [Installing](?no-link-check#install)
- [Uninstalling](?no-link-check#uninstall)
Expand All @@ -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)
<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
Expand All @@ -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)
(<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
- <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/)
Expand All @@ -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)
(<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)
(<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/)
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling>)
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/),
`/docs/2.13/troubleshooting/`
Comment on lines -126 to +128
Copy link
Collaborator Author

@chalin chalin Feb 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nate-double-u FYI: the current markdown linter rules report bare URLs, and use that config because it often finds errors like these, of misformatted links.

- 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)
<https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec>)
- ScaledJob specification
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec)
(<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)
- ...
Expand Down Expand Up @@ -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
<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
Expand Down
49 changes: 25 additions & 24 deletions analyses/0011-keda/keda-issues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
---
title: KEDA Umbrella Issue
tags: keda
cSpell:ignore: externalscaler findability
---

<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->

# Overview

This document outlines the recommended changes to the KEDA documentation. The
Expand Down Expand Up @@ -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
<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
Expand All @@ -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
- <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
Expand All @@ -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)
(<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)
Expand All @@ -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)
(<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)
(<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/)
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling>)
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/)
`/docs/2.13/troubleshooting/`

## Issue: Create a "Reference" topic

Expand All @@ -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)
<https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec>)
- ScaledJob specification
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec)
(<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)
- ...
Expand All @@ -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 | <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". |

# Write a Glossary

Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)",
Expand Down