mirror of https://github.com/cncf/techdocs.git
Keda analysis (#215)
KEDA documentation analysis, implementation plan, and issues list. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: David Welsch <dw@cluemail.com> Signed-off-by: thisisobate <obasiuche62@gmail.com> Co-authored-by: thisisobate <obasiuche62@gmail.com> Co-authored-by: David Welsch <dw@cluemail.com>
This commit is contained in:
Dave Welsch
GitHub
parent
c73ed78ae3
commit
d760e0c912
|
|
@ -0,0 +1,416 @@
|
|||
---
|
||||
title: KEDA Documentation Analysis
|
||||
tags: kdeda
|
||||
created: 2024-02-23
|
||||
modified: 2024-04-09
|
||||
author: Dave Welsch (@dwelsch-esi)
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
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:
|
||||
|
||||
- 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
|
||||
|
||||
## 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 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.
|
||||
|
||||
**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/governanace
|
||||
- Main project contributor info: https://github.com/kedacore/keda
|
||||
|
||||
**Out of scope:**
|
||||
- Other KEDA repos: https://github.com/kedacore/*
|
||||
|
||||
## How this document is organized
|
||||
|
||||
This document is divided into three sections that represent three major areas of concern:
|
||||
|
||||
- **Project documentation:** concerns documentation for users of the KEDA software, aimed at people who intend to use it
|
||||
- **Contributor documentation:** concerns documentation for new and existing contributors to the KEDA OSS project
|
||||
- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
|
||||
## How to use this document
|
||||
|
||||
Readers interested only in actionable improvements should skip this document and read [keda-implementation.md](./keda-implementation.md).
|
||||
|
||||
Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern:
|
||||
|
||||
- [Project documentation](#project-documentation)
|
||||
- [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.
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
# Project documentation
|
||||
|
||||
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) |
|
||||
| --- | --- |
|
||||
| Information architecture | 2 - needs improvement |
|
||||
| New user content | 2 - needs improvement |
|
||||
| Content maintainability | 3 - meets standards |
|
||||
| Content creation processes | 2 - needs improvement |
|
||||
| Inclusive language | 2 - needs improvement |
|
||||
|
||||
|
||||
## Comments
|
||||
|
||||
### Information architecture
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
There are **escalation paths** available:
|
||||
- The documentation contains a Troubleshooting section.
|
||||
- The documentation contains a FAQ.
|
||||
- The website has a blog, though posts are infrequent.
|
||||
- The project has a Support page available from the website menu at Project > Support. The support page links to a contributor guide and a support policy page.
|
||||
- There is a KEDA Slack channel in the Kubernetes workspace.
|
||||
- There is a KEDA Discussions forum in the GitHub repo.
|
||||
|
||||
KEDA does not feature an **API** per se.
|
||||
|
||||
The documentation **is versioned** with the software; doc versions each have their own directory in the repo. Release notes are provided in the project main repo, and linked from a ROADMAP file. They are not linked from the documentation pages.
|
||||
|
||||
### New user content
|
||||
|
||||
There is partial **getting started** information in the documentation as [Deploying KEDA](https://keda.sh/docs/2.13/deploy/), the first topic in the table of contents. *Deploying KEDA* provides **installation instruction** for adding a KEDA runtime to a Kubernetes cluster.
|
||||
|
||||
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 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.
|
||||
|
||||
There are also numerous examples available in the [samples repo](https://github.com/kedacore/samples).
|
||||
|
||||
KEDA does not require documentation for multiple **operating systems**.
|
||||
|
||||
The [Operate](https://keda.sh/docs/2.13/operate/) topic in the TOC provides instructions for using KEDA and the scenarios in the repo provide user instructions. However, new users starting on the website might not **know where to go after installation**. A more explicit **getting started workflow** would be helpful.
|
||||
|
||||
There is no obvious **new user signpost** in the documentation. The closest is *Deploying KEDA*, which again just gives installation instructions but no roadmap.
|
||||
|
||||
There is easily **copy-pastable** content for CLI input where appropriate, including in the installation instructions.
|
||||
|
||||
### Content maintainability & site mechanics
|
||||
|
||||
The documentation is **Searchable** using functionality provided by the site generation engine.
|
||||
|
||||
There do not seem to be any plans for **localization**. Docsy has **support for multiple languages** in case that changes.
|
||||
|
||||
The documentation is **versioned**. The repo contains a separate folder for each version.
|
||||
|
||||
### Content creation processes
|
||||
|
||||
The procedure for **building and releasing a new version** is documented in the doc repo README file.
|
||||
|
||||
The code contribution instructions contain brief **documentation creation and update** instructions.
|
||||
|
||||
The MAINTAINERS doc in the website repo points to the MAINTAINERS doc in the main repo, which does not tell who is **responsible for documentation pull requests**. The website does not have a **clear owner or maintainer**.
|
||||
|
||||
### Inclusive language
|
||||
|
||||
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
|
||||
|
||||
### Information architecture
|
||||
|
||||
Reorganize the Table of Contents. Rename "The KEDA Documentation"; the name is misleading since it implies that it contains the entire documentation set. I'd suggest the following changes:
|
||||
- Rename "The KEDA Documentation" to "Getting Started".
|
||||
- Create a "Reference" topic at the end of the ToC.
|
||||
- Move the FAQ to the Reference section.
|
||||
- Add a glossary to the Reference section.
|
||||
- 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.
|
||||
|
||||
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.
|
||||
|
||||
### New user content
|
||||
|
||||
Clearly label the starting point for new users. Make sure that there is an easy to follow workflow for installation, configuring and running a basic scaler, and any other tasks required to begin using KEDA.
|
||||
|
||||
### Content maintainability & site mechanics
|
||||
|
||||
No recommendations
|
||||
|
||||
### Content creation processes
|
||||
|
||||
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.
|
||||
|
||||
### Inclusive language
|
||||
|
||||
Remove non-inclusive language throughout the documentation as recommended on the [inclusive naming website](https://inclusivenaming.org/).
|
||||
|
||||
|
||||
# Contributor documentation
|
||||
|
||||
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 |
|
||||
| Beginner friendly issue backlog | 3 - meets 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**.
|
||||
|
||||
|
||||
### Beginner friendly issue backlog
|
||||
|
||||
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).
|
||||
|
||||
There are **stale issues**, but they seem for the most part to be managed. There are only ~30 open issues in the doc repo.
|
||||
|
||||
|
||||
### New contributor getting started content
|
||||
|
||||
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.
|
||||
|
||||
|
||||
### Project governance documentation
|
||||
|
||||
**Governance** is clearly documented in its own repo. Presumably this information is applicable to all of the repos in kedacore.
|
||||
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Communication methods documented
|
||||
|
||||
If there is a mailing list or other news distribution channel, add it to the community page. (Note: As discussed in the [PR](https://github.com/cncf/techdocs/pull/215), there does not seem to be a newsletter. This is OK since there are plenty of other active communication channels.)
|
||||
|
||||
|
||||
### Beginner friendly issue backlog
|
||||
|
||||
Revisit stale issues if they are not being reviewed.
|
||||
|
||||
|
||||
### New contributor getting started content
|
||||
|
||||
No recommendations.
|
||||
|
||||
|
||||
### Project governance documentation
|
||||
|
||||
No recommendations.
|
||||
|
||||
|
||||
# Website
|
||||
|
||||
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) |
|
||||
| --- | --- |
|
||||
| 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 |
|
||||
| Branding and design | 4 - meets or exceeds standards |
|
||||
| Case studies/social proof | 3 - meets standards |
|
||||
| SEO, Analytics, and site-local search | 4 - meets or exceeds standards |
|
||||
| Maintenance planning | 4 - meets or exceeds standards |
|
||||
| A11y plan & implementation | 3 - meets standards |
|
||||
| Mobile-first plan & impl. | 4 - meets or exceeds standards |
|
||||
| HTTPS access & HTTP redirect | 4 - meets or exceeds standards |
|
||||
| Google Analytics 4 for production only | 5 - exemplary |
|
||||
| Indexing allowed for production server only | 5 - exemplary |
|
||||
| Intra-site / local search | 5 - exemplary |
|
||||
| Account custodians are documented | 2 - needs improvement |
|
||||
|
||||
|
||||
## Comments
|
||||
|
||||
### Single-source requirement
|
||||
|
||||
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.
|
||||
|
||||
|
||||
### Minimal website requirements
|
||||
|
||||
Except for archived projects, requirements are cumulative through project maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects.
|
||||
|
||||
Listed and acknowledged below are the (cumulative) _minimal_ website requirements for projects based on their [maturity level](https://github.com/cncf/toc/tree/main/process#cncf-project-lifecycle--process): sandbox, incubating, graduated and archived.
|
||||
|
||||
| Maturity | Requirement | Met? |
|
||||
| --- | --- | --- |
|
||||
| Sandbox | Majority of [Website guidelines](https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md) satisfied | Yes |
|
||||
| Sandbox | [Docs assessment](https://github.com/cncf/techdocs/blob/main/assessments/howto.md) [cncf-servicedesk] completed. | Yes |
|
||||
| Sandbox | **Project documentation** exists – somewhere. It is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website. (May still be in the project GitHub repo, for example.) | Yes |
|
||||
| Incubating | All [Website guidelines](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md#website) satisfied | Yes |
|
||||
| Incubating | Request docs (re-)assessment through CNCF [service desk](https://servicedesk.cncf.io/) | Yes |
|
||||
| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | No |
|
||||
| Incubating | **Project doc**: Hosted directly | Yes |
|
||||
| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | Yes |
|
||||
| Graduated | [Docs assessment](https://github.com/cncf/techdocs/blob/main/assessments/howto.md): all assessment follow-through actions are complete | No |
|
||||
| Graduated | **Project doc** fully addresses needs of key stakeholders | No - new user doc needs improvement |
|
||||
| Archived | The website repo is in an [archived state](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) | n/a |
|
||||
| Archived | Archived status of the project is obvious to site visitors | n/a |
|
||||
| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a |
|
||||
|
||||
### Usability, accessibility and devices
|
||||
|
||||
The website is **usable from mobile**. Top-nav is reachable only via the hamburger menu on mobile devices. There is no in-page TOC or other context on mobile devices. The footer is identical on all platforms.
|
||||
|
||||
**Search** is available from the hamburger menu as well.
|
||||
|
||||
**Doc pages are readable** on all platforms.
|
||||
|
||||
A **mobile-first design** does not make sense for this project.
|
||||
|
||||
**Color contrasts** are mostly adequate. Some blue-on-black graphics and text are probably hard to read for color- or contrast-impaired readers.
|
||||
|
||||
Website features, *Search* most importantly, are usable using a **keyboard only**.
|
||||
|
||||
As with any text that contains a lot of code and special characters, **text-to-speech** is **not likely to offer listeners a good experience**.
|
||||
|
||||
### Branding and design
|
||||
|
||||
The website and documentation carry an **easily recognizable brand** for the project based on logo, color scheme, and template layout. The **brand is used consistently** on the site. The website's text is **easily readable**.
|
||||
|
||||
|
||||
### Case studies/social proof
|
||||
|
||||
|
||||
I'm unable to find **case studies** or **user testimonials** for the project. They're probably not as important for KEDA as they are for a more extensive product, though.
|
||||
|
||||
There is a **project blog**; posts are infrequent. The last one was in August 2023.
|
||||
|
||||
There are **community talks** for the project on YouTube. One talk, from KubeCon 2022, is **present on the website**.
|
||||
|
||||
There is a substantial **logo wall of users and participating organizations**. The KEDA project solicits users to register as "listed users."
|
||||
|
||||
|
||||
### SEO, Analytics and site-local search
|
||||
|
||||
**Analytics:**
|
||||
* Analytics is enabled for the production server.
|
||||
* Analytics is disabled for all other deployments.
|
||||
* The website runs on the new Google Analytics (GA) 4.
|
||||
* 404 reports are collected and tracked using GA4.
|
||||
|
||||
**Indexing and Search:**
|
||||
* The production site is well indexed.
|
||||
* Local intra-site search available is from the website.
|
||||
|
||||
**Account custodians**
|
||||
* There are no records showing the different account custodians; nothing is listed on `MAINTAINERS.md` and no `OWNERS.md` is found.
|
||||
|
||||
### Maintenance planning
|
||||
|
||||
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).
|
||||
|
||||
**Build times** for the website are minimal.
|
||||
|
||||
Presumably, **site maintainers have adequate permissions** since the documentation is up to date with the software.
|
||||
|
||||
|
||||
### Other
|
||||
|
||||
The website is accessible via **HTTPS**. Requests using **HTTP** are properly redirected to the **HTTPS** URLs.
|
||||
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Single-source requirement
|
||||
|
||||
No recommendations.
|
||||
|
||||
### Minimal website requirements
|
||||
|
||||
Identify stakeholder roles in the user documentation (even if there is only one role). This could be as minimal as a "who should use this documentation" paragraph in the product introduction.
|
||||
|
||||
Update docs per Implementation and Issues recommendations (separate documents). Especially, improve new user documentation.
|
||||
|
||||
|
||||
### Usability, accessibility and devices
|
||||
|
||||
No recommendations.
|
||||
|
||||
|
||||
### Branding and design
|
||||
|
||||
No recommendations.
|
||||
|
||||
|
||||
### Case studies/social proof
|
||||
|
||||
No recommendations.
|
||||
|
||||
|
||||
### SEO, Analytics and site-local search
|
||||
|
||||
The current custodian(s) of the following accounts should be clearly documented: analytics (GA4), site-search (Algolia). You can create an `OWNERS.md` file for this.
|
||||
|
||||
### Maintenance planning
|
||||
|
||||
Explicitly list and solicit maintainers and contributors for documentation.
|
||||
|
||||
|
||||
### Other
|
||||
|
||||
No recommendations.
|
||||
|
||||
|
||||
<!--- References --->
|
||||
|
|
@ -0,0 +1,188 @@
|
|||
---
|
||||
title: Implementing KEDA Doc Improvements
|
||||
tags: keda
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
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.
|
||||
|
||||
The documentation recommendations for this project are:
|
||||
- [Reorganize the table of contents (TOC)](#reorganize-the-table-of-contents-toc)
|
||||
- [Write a glossary](#write-a-glossary)
|
||||
- [Add "How to set up a scaler" to the Operator guide](#add-how-to-set-up-a-scaler-to-the-operator-guide)
|
||||
- [Write a New User workflow](#write-a-new-user-workflow)
|
||||
- [Update the doc content creation instructions](#update-the-doc-content-creation-instructions)
|
||||
- [Remove non-inclusive language](#remove-non-inclusive-language)
|
||||
- [Make user roles explicit](#make-user-roles-explicit)
|
||||
- [Clarify documentation maintainers](#clarify-documentation-maintainers)
|
||||
|
||||
|
||||
# Reorganize the Table of Contents
|
||||
|
||||
Reorganize the Table of Contents to:
|
||||
|
||||
- Better welcome and orient new users
|
||||
- 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.
|
||||
- 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).
|
||||
- Include a clear starting point and ramp-up path for new users.
|
||||
|
||||
Here is a proposed outline for the tech doc Table of Contents:
|
||||
|
||||
- [KEDA Concepts](/docs/2.13/concepts/)
|
||||
- What is KEDA?
|
||||
- How KEDA works
|
||||
- KEDA Architecture
|
||||
- KEDA Custom Resources (CRDs)
|
||||
- [Scaling Deployments, StatefulSets & Custom Resources](/docs/2.13/concepts/scaling-deployments/)
|
||||
- Overview
|
||||
- Scaling Deployments and Stateful Sets
|
||||
- Scaling Custom Resources
|
||||
- [Scaling Jobs](/docs/2.13/concepts/scaling-jobs/)
|
||||
- [Authentication](/docs/2.13/concepts/authentication/)
|
||||
- [External Scalers](/docs/2.13/concepts/external-scalers/)
|
||||
- [Admission Webhooks](/docs/2.13/concepts/admission-webhooks/)
|
||||
- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA Documentation" heading)
|
||||
- [Deploying KEDA](/docs/2.13/deploy/)
|
||||
- Prerequisites (https://keda.sh/docs/2.13/operate/cluster/#requirements)
|
||||
- [Deploying with Helm](#helm)
|
||||
- [Installing](#install)
|
||||
- [Uninstalling](#uninstall)
|
||||
- [Deploying with Operator Hub](#operatorhub)
|
||||
- [Installing](#install-1)
|
||||
- [Uninstalling](#uninstall-1)
|
||||
- [Deploying using the deployment YAML files](#yaml)
|
||||
- [Installing](#install-2)
|
||||
- [Uninstalling](#uninstall-2)
|
||||
- [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)
|
||||
- [Using KEDA or Operator Guide](/docs/2.13/operate/) (rename current "Operate")
|
||||
- How to set up a scaler (a more detailed procedure than the example used in Getting Started)
|
||||
- Usage Scenarios
|
||||
- [Scaling with RabbitMQ and Go](https://github.com/kedacore/sample-go-rabbitmq)
|
||||
- [Scaling with Azure Functions and Kafka on Openshift 4](https://github.com/kedacore/sample-azure-functions-on-ocp4)
|
||||
- ... and so on.
|
||||
- [Admission Webhooks](/docs/2.13/operate/admission-webhooks/)
|
||||
- Prevention Rules (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules)
|
||||
- Validation Enforcement
|
||||
- [Cluster](/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)](/docs/2.13/operate/opentelemetry/)
|
||||
- [Integrating with Prometheus](/docs/2.13/operate/prometheus/)
|
||||
- [Using the KEDA Metrics Server](/docs/2.13/operate/metrics-server/)
|
||||
- [Querying Metrics](https://keda.sh/docs/2.13/operate/metrics-server/#querying-metrics-exposed-by-keda-metrics-server)
|
||||
- [Getting Metric Names](https://keda.sh/docs/2.13/operate/metrics-server/#how-to-get-metric-names-from-scaledobject)
|
||||
- [Security](/docs/2.13/operate/security/)
|
||||
- [Migrating to a new release](/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](/docs/2.13/concepts/troubleshooting/, /docs/2.13/troubleshooting/)
|
||||
- Reference
|
||||
- [Authentication Providers](/docs/2.13/authentication-providers/)
|
||||
- [AWS (IRSA) Pod Identity Webhook](/docs/2.13/authentication-providers/aws/)
|
||||
- ...
|
||||
- [Secret](/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](/docs/2.13/operate/events/)
|
||||
- [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall)
|
||||
- ...
|
||||
- [FAQ](/docs/2.13/faq/)
|
||||
- Glossary
|
||||
- [Scalers](/docs/2.13/scalers/)
|
||||
- [ActiveMQ](/docs/2.13/scalers/activemq/)
|
||||
- ...
|
||||
- [Solr](/docs/2.13/scalers/solr/)
|
||||
|
||||
Among other things, the reorganization includes these changes:
|
||||
|
||||
- Rename "The KEDA Documentation" to "Getting Started".
|
||||
- Create a "Reference" topic at the end of the ToC.
|
||||
- Move the FAQ to the Reference section.
|
||||
- Add a glossary to the Reference section.
|
||||
- Rename "Operate" to "Operator Guide".
|
||||
- Move "Troubleshooting" to the end of the User Guide.
|
||||
- Separate reference and task information that appears on the same page and move each to the appropriate section.
|
||||
|
||||
# Write a Glossary
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.*
|
||||
* [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)
|
||||
- [Uninstalling](#uninstall) *
|
||||
* [Deploying with Operator Hub](#operatorhub)
|
||||
- [Installing](#install-1)
|
||||
- [Uninstalling](#uninstall-1)
|
||||
* [Deploying using the deployment YAML files](#yaml)
|
||||
- [Installing](#install-2)
|
||||
- [Uninstalling](#uninstall-2)
|
||||
* [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*
|
||||
|
||||
|
||||
# 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".
|
||||
|
||||
Document in the repo (keda-docs, keda, or both) who the website/documentation maintainers are.
|
||||
|
||||
# Remove non-inclusive language
|
||||
|
||||
Remove non-inclusive language throughout the documentation as recommended by the [Inclusive Naming Initiative](https://inclusivenaming.org/).
|
||||
|
||||
# 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.
|
||||
|
||||
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).
|
||||
|
||||
Explicitly list and solicit maintainers and contributors for documentation, either in the new OWNERS file or the governance MAINTAINERS file.
|
||||
|
||||
|
||||
<!--- References --->
|
||||
|
||||
[keda-analysis]: ./keda-analysis.md
|
||||
[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119
|
||||
|
|
@ -0,0 +1,232 @@
|
|||
---
|
||||
title: KEDA Umbrella Issue
|
||||
tags: keda
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
This document outlines the recommended changes to the KEDA documentation. The following issues are added to the [project repo](https://github.com/kedacore/keda-docs).
|
||||
|
||||
# Issue: Reorganize the Table of Contents
|
||||
|
||||
Reorganize the Table of Contents to:
|
||||
|
||||
- Better welcome and orient new users
|
||||
- Separate user roles (personas), if there are more than one
|
||||
- Improve findability and access to tasks and procedures
|
||||
- Separate conceptual, task, and reference information
|
||||
|
||||
Here is a proposed high-level outline for the tech doc Table of Contents. Work on individual sections is broken out into sub-issues.
|
||||
|
||||
- [KEDA Concepts](https://keda.sh/docs/2.13/concepts/). See [Reorganize Concepts](#issue-reorganize-concepts).
|
||||
- [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename current "KEDA Documentation" heading). See [Write a "Getting Started" Guide](#issue-write-a-getting-started-guide).
|
||||
- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename current "Operate"). See [Update the Operator Guide](#issue-update-the-operator-guide).
|
||||
- Reference. See [Create a Reference](#issue-create-a-reference-topic).
|
||||
- [Scalers](https://keda.sh/docs/2.13/scalers/).
|
||||
|
||||
|
||||
## Issue: Reorganize Concepts
|
||||
|
||||
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.
|
||||
|
||||
- [KEDA Concepts](https://keda.sh/docs/2.13/concepts/)
|
||||
- What is KEDA?
|
||||
- How KEDA works
|
||||
- KEDA Architecture
|
||||
- KEDA Custom Resources (CRDs)
|
||||
- [Scaling Deployments, StatefulSets and Custom Resources](https://keda.sh/docs/2.13/concepts/scaling-deployments/)
|
||||
- Overview
|
||||
- Scaling Deployments and Stateful Sets
|
||||
- Scaling Custom Resources
|
||||
- [Scaling Jobs](https://keda.sh/docs/2.13/concepts/scaling-jobs/)
|
||||
- [Authentication](https://keda.sh/docs/2.13/concepts/authentication/)
|
||||
- [External Scalers](https://keda.sh/docs/2.13/concepts/external-scalers/)
|
||||
- [Admission Webhooks](https://keda.sh/docs/2.13/concepts/admission-webhooks/)
|
||||
|
||||
|
||||
## Issue: Write a "Getting Started" guide
|
||||
|
||||
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.
|
||||
|
||||
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.*
|
||||
- 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)
|
||||
- [Installing](#install)
|
||||
- [Uninstalling](#uninstall)
|
||||
- [Deploying with Operator Hub](#operatorhub)
|
||||
- [Installing](#install-1)
|
||||
- [Uninstalling](#uninstall-1)
|
||||
- [Deploying using the deployment YAML files](#yaml)
|
||||
- [Installing](#install-2)
|
||||
- [Uninstalling](#uninstall-2)
|
||||
- [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*
|
||||
|
||||
|
||||
## Issue: Update the Operator Guide
|
||||
|
||||
Some guidelines:
|
||||
|
||||
- Can be named "Using KEDA" or "Operator Guide".
|
||||
- Base the guide on the existing "Operator" section.
|
||||
- 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 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.
|
||||
|
||||
- [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))
|
||||
- Usage Scenarios
|
||||
- [Scaling with RabbitMQ and Go](https://github.com/kedacore/sample-go-rabbitmq)
|
||||
- [Scaling with Azure Functions and Kafka on Openshift 4](https://github.com/kedacore/sample-azure-functions-on-ocp4)
|
||||
- ... 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)
|
||||
- Using HTTP
|
||||
[Setting Timeouts](https://keda.sh/docs/2.13/operate/cluster/#http-timeouts)
|
||||
[Disabling Keep-alive](https://keda.sh/docs/2.13/operate/cluster/#http-connection-disable-keep-alive)
|
||||
[Using HTTP Proxies](https://keda.sh/docs/2.13/operate/cluster/#http-proxies)
|
||||
[Configuring Minimum TLS Version]
|
||||
- [Integrating with OpenTelemetry Collector (Experimental)](https://keda.sh/docs/2.13/operate/opentelemetry/)
|
||||
- [Integrating with Prometheus](https://keda.sh/docs/2.13/operate/prometheus/)
|
||||
- [Using the KEDA Metrics Server](https://keda.sh/docs/2.13/operate/metrics-server/)
|
||||
- [Querying Metrics](https://keda.sh/docs/2.13/operate/metrics-server/#querying-metrics-exposed-by-keda-metrics-server)
|
||||
- [Getting Metric Names](https://keda.sh/docs/2.13/operate/metrics-server/#how-to-get-metric-names-from-scaledobject)
|
||||
- [Security](https://keda.sh/docs/2.13/operate/security/)
|
||||
- [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/)
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
- 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)
|
||||
- ...
|
||||
- [FAQ](https://keda.sh/docs/2.13/faq/)
|
||||
- Glossary
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
| 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/operate/prometheus/ | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". |
|
||||
|
||||
# Write a Glossary
|
||||
|
||||
Create a glossary of terms specific to KEDA. It wouldn't hurt to include some key Kubernetes terms as well, especially acronyms. Add to the Reference section.
|
||||
|
||||
Here is a partial list of terms to include:
|
||||
|
||||
- Admission Webhook
|
||||
- Agent
|
||||
- Cluster
|
||||
- CRD
|
||||
- Event
|
||||
- Event Source
|
||||
- Grafana
|
||||
- GRPC
|
||||
- HPA
|
||||
- KEDA
|
||||
- Metrics
|
||||
- OpenTelemetry
|
||||
- Operator
|
||||
- Prometheus
|
||||
- Scaled Object
|
||||
- Scaled Job
|
||||
- Scaler
|
||||
- Stateful Set
|
||||
- TLS
|
||||
- Webhook
|
||||
|
||||
For an example from another CNCF project, see the [glossary in the Backstage documentation](https://backstage.io/docs/references/glossary/).
|
||||
|
||||
# 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.
|
||||
|
||||
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.
|
||||
|
||||
The definition of the Operator role could be as minimal as a "who should use this documentation" paragraph in the product introduction.
|
||||
|
||||
|
||||
# Update the doc content creation instructions
|
||||
|
||||
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".
|
||||
|
||||
|
||||
# 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).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
# Remove non-inclusive language
|
||||
|
||||
Remove non-inclusive language throughout the documentation as recommended by the [Inclusive Naming Initiative](https://inclusivenaming.org/). Some examples of non-inclusive language in KEDA:
|
||||
|
||||
- In [concepts/scaling-deployments.md](https://keda.sh/docs/2.13/concepts/scaling-deployments/): "This value can be used to easily distinguish this specific trigger and its metrics ..."
|
||||
- The use of "master" (as in "sentinelMaster") in [scalers/redis-sentinel-lists.md](https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/). This might be impossible to change without changing the Redis scaler as well.)
|
||||
- In [deploy.md](https://keda.sh/docs/2.13/deploy/): "Deploying KEDA with Helm is very simple".
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue