Skip to main content

Overview

This document outlines the recommended changes to the KEDA documentation. The following issues are added to the project repo.

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.

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.

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.

Issue: Update the Operator Guide​

Some guidelines:

Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point.

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.

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 TitleURLNotes
Deploying KEDAhttps://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 Resourceshttps://keda.sh/docs/2.13/concepts/scaling-deployments/The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task.
Scaling Jobshttps://keda.sh/docs/2.13/concepts/scaling-jobs/"ScaledJob spec" is reference information.
Authenticationhttps://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 Scalershttps://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.
Troubleshootinghttps://keda.sh/docs/2.13/concepts/troubleshooting/Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation".
Clusterhttps://keda.sh/docs/2.13/operate/cluster/See the "Update the Operator Guide" issue
Eventshttps://keda.sh/docs/2.13/operate/events/This is reference information.
Integrate with Prometheushttps://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

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.

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:

  • 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. Some examples of non-inclusive language in KEDA: