Skip to content

Commit bb1228f

Browse files
chalinchalin
committed
[chore] Check Keda analysis pages
Signed-off-by: Patrice Chalin <[email protected]>
1 parent 64b6ce9 commit bb1228f

File tree

4 files changed

+55
-51
lines changed

4 files changed

+55
-51
lines changed

‎analyses/0011-keda/keda-analysis.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ author: Dave Welsch (@dwelsch-esi)
66
cSpell:ignore: Welsch dwelsch pastable servicedesk
77
---
88

9+
<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->
10+
911
# Introduction
1012

1113
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.
4648

4749
**In scope:**
4850

49-
- Website: https://keda.sh
50-
- Documentation: https://keda.sh/docs
51-
- Website repo: https://github.com/kedacore/keda-docs
52-
- Governance repo: https://github.com/kedacore/governance
53-
- Main project contributor info: https://github.com/kedacore/keda
51+
- Website: <https://keda.sh>
52+
- Documentation: <https://keda.sh/docs>
53+
- Website repo: <https://github.com/kedacore/keda-docs>
54+
- Governance repo: <https://github.com/kedacore/governance>
55+
- Main project contributor info: <https://github.com/kedacore/keda>
5456

5557
**Out of scope:**
5658

57-
- Other KEDA repos: https://github.com/kedacore/*
59+
- Other KEDA repos under <https://github.com/kedacore/>
5860

5961
## How this document is organized
6062

@@ -233,12 +235,12 @@ The documentation includes some examples of
233235
[**non-inclusive language**](https://inclusivenaming.org/). For example:
234236

235237
- "easily", "simple", "simply", etc.
236-
- https://keda.sh/docs/2.13/deploy/
237-
- https://keda.sh/docs/2.13/deploy/#uninstall-3
238-
- https://keda.sh/docs/2.13/concepts/scaling-deployments/#triggers
238+
- <https://keda.sh/docs/2.13/deploy/>
239+
- <https://keda.sh/docs/2.13/deploy/#uninstall-3>
240+
- <https://keda.sh/docs/2.13/concepts/scaling-deployments/#triggers>
239241
- "master" node
240-
- https://keda.sh/docs/2.13/troubleshooting/#google-kubernetes-engine-gke
241-
- https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/#authentication-parameters
242+
- <https://keda.sh/docs/2.13/troubleshooting/#google-kubernetes-engine-gke>
243+
- <https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/#authentication-parameters>
242244

243245
## Recommendations
244246

‎analyses/0011-keda/keda-implementation.md‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
---
22
title: Implementing KEDA Doc Improvements
3-
tags: keda
43
---
54

5+
<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->
6+
67
# Introduction
78

89
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:
7677
- [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename
7778
current "KEDA Documentation" heading)
7879
- [Deploying KEDA](https://keda.sh/docs/2.13/deploy/)
79-
- Prerequisites (https://keda.sh/docs/2.13/operate/cluster/#requirements)
80+
- Prerequisites (<https://keda.sh/docs/2.13/operate/cluster/#requirements>)
8081
- [Deploying with Helm](?no-link-check#helm)
8182
- [Installing](?no-link-check#install)
8283
- [Uninstalling](?no-link-check#uninstall)
@@ -91,7 +92,7 @@ Here is a proposed outline for the tech doc Table of Contents:
9192
- [Uninstalling](?no-link-check#uninstall-3)
9293
- Hello, KEDA (write a procedure for a simplest-possible use case for users to
9394
get started on - something like
94-
https://github.com/kedacore/sample-hello-world-azure-functions)
95+
<https://github.com/kedacore/sample-hello-world-azure-functions>)
9596
- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename
9697
current "Operate")
9798
- 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:
102103
- ... and so on.
103104
- [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/)
104105
- Prevention Rules
105-
(https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules)
106+
(<https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules>)
106107
- Validation Enforcement
107108
- [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - Except sections that
108109
are purely reference info, for example:
109-
- https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility
110-
- https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity
111-
- https://keda.sh/docs/2.13/operate/cluster/#firewall
110+
- <https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility>
111+
- <https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity>
112+
- <https://keda.sh/docs/2.13/operate/cluster/#firewall>
112113
- [Integrating with OpenTelemetry Collector (Experimental)](https://keda.sh/docs/2.13/integrations/opentelemetry/)
113114
- [Integrating with Prometheus](https://keda.sh/docs/2.13/integrations/prometheus/)
114115
- [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:
118119
- [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current
119120
"Migration Guide")
120121
- Caching Metrics
121-
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics)
122+
(<https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics>)
122123
- Pausing Autoscaling of deployments
123-
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling)
124+
(<https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling>)
124125
- Pausing Autoscaling of jobs
125-
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling)
126-
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/,
127-
/docs/2.13/troubleshooting/)
126+
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling>)
127+
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/),
128+
`/docs/2.13/troubleshooting/`
128129
- Reference
129130
- [Authentication Providers](https://keda.sh/docs/2.13/authentication-providers/)
130131
- [AWS (IRSA) Pod Identity Webhook](https://keda.sh/docs/2.13/authentication-providers/aws/)
131132
- ...
132133
- [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/)
133134
- Scaled Object specification (from "Concepts";
134-
https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec)
135+
<https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec>)
135136
- ScaledJob specification
136-
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec)
137+
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec>)
137138
- [Events](https://keda.sh/docs/2.13/operate/events/)
138139
- [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall)
139140
- ...
@@ -210,7 +211,7 @@ annotated to illustrate this point:
210211
- [Uninstalling](?no-link-check#uninstall-3)
211212
- Hello, KEDA (write a procedure for a simplest-possible use case for users to
212213
get started on - something like
213-
https://github.com/kedacore/sample-hello-world-azure-functions) _analogous
214+
<https://github.com/kedacore/sample-hello-world-azure-functions>) _analogous
214215
to a "Hello World" exercise in programming language or API guides_
215216

216217
# Update the doc content creation instructions

‎analyses/0011-keda/keda-issues.md‎

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
22
title: KEDA Umbrella Issue
3-
tags: keda
43
cSpell:ignore: externalscaler findability
54
---
65

6+
<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->
7+
78
# Overview
89

910
This document outlines the recommended changes to the KEDA documentation. The
@@ -98,7 +99,7 @@ into multiple pages, one for each procedure.
9899
- [Uninstalling](?no-link-check#uninstall-3)
99100
- Hello, KEDA (write a procedure for a simplest-possible use case for users to
100101
get started on - something like
101-
https://github.com/kedacore/sample-hello-world-azure-functions) _analogous
102+
<https://github.com/kedacore/sample-hello-world-azure-functions>) _analogous
102103
to a "Hello World" exercise in programming language or API guides_
103104

104105
## Issue: Update the Operator Guide
@@ -110,9 +111,9 @@ Some guidelines:
110111
- Move "Troubleshooting" to the end of the Operator Guide.
111112
- Relocate sections that are purely reference information, including these
112113
sections in [Cluster](https://keda.sh/docs/2.13/operate/cluster/):
113-
- https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility
114-
- https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity
115-
- https://keda.sh/docs/2.13/operate/cluster/#firewall
114+
- <https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility>
115+
- <https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity>
116+
- <https://keda.sh/docs/2.13/operate/cluster/#firewall>
116117
- Break up long pages containing several topics. Aim for one major topic per
117118
page. For example, all HTTP-related headings on the
118119
[Cluster](https://keda.sh/docs/2.13/operate/cluster/) page could go on one
@@ -132,7 +133,7 @@ or provide a starting point.
132133
- ... and so on.
133134
- [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/)
134135
- Prevention Rules
135-
(https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules)
136+
(<https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules>)
136137
- Validation Enforcement
137138
- [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - (Relocate sections
138139
that are purely reference info)
@@ -150,13 +151,13 @@ or provide a starting point.
150151
- [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current
151152
"Migration Guide")
152153
- Caching Metrics
153-
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics)
154+
(<https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics>)
154155
- Pausing Autoscaling of deployments
155-
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling)
156+
(<https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling>)
156157
- Pausing Autoscaling of jobs
157-
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling)
158-
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/,
159-
/docs/2.13/troubleshooting/)
158+
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling>)
159+
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/)
160+
`/docs/2.13/troubleshooting/`
160161

161162
## Issue: Create a "Reference" topic
162163

@@ -174,9 +175,9 @@ or provide a starting point.
174175
- ...
175176
- [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/)
176177
- Scaled Object specification (from "Concepts";
177-
https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec)
178+
<https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec>)
178179
- ScaledJob specification
179-
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec)
180+
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec>)
180181
- [Events](https://keda.sh/docs/2.13/operate/events/)
181182
- [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall)
182183
- ...
@@ -201,17 +202,17 @@ information. Some of these pages might appear in other issues suggesting that
201202
they be revised or relocated. If this creates contradictory recommendations,
202203
some judgement might be required to rearrange things.
203204

204-
| Page Title | URL | Notes |
205-
| ------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
206-
| 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. |
207-
| 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. |
208-
| Scaling Jobs | https://keda.sh/docs/2.13/concepts/scaling-jobs/ | "ScaledJob spec" is reference information. |
209-
| 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. |
210-
| 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. |
211-
| Troubleshooting | https://keda.sh/docs/2.13/concepts/troubleshooting/ | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". |
212-
| Cluster | https://keda.sh/docs/2.13/operate/cluster/ | See the "Update the Operator Guide" issue |
213-
| Events | https://keda.sh/docs/2.13/operate/events/ | This is reference information. |
214-
| 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". |
205+
| Page Title | URL | Notes |
206+
| ------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
207+
| 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. |
208+
| 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. |
209+
| Scaling Jobs | <https://keda.sh/docs/2.13/concepts/scaling-jobs/> | "ScaledJob spec" is reference information. |
210+
| 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. |
211+
| 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. |
212+
| Troubleshooting | <https://keda.sh/docs/2.13/concepts/troubleshooting/> | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". |
213+
| Cluster | <https://keda.sh/docs/2.13/operate/cluster/> | See the "Update the Operator Guide" issue |
214+
| Events | <https://keda.sh/docs/2.13/operate/events/> | This is reference information. |
215+
| 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". |
215216

216217
# Write a Glossary
217218

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
"_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml",
1313
"_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'",
1414
"_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path '*/00*'",
15-
"_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010|/0011'",
15+
"_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010'",
1616
"_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'",
1717
"_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'",
1818
"check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",

0 commit comments

Comments
 (0)