Reorganize Concepts

[dwelsch-esi]

Remove everything that's not a conceptual overview. Separate task and reference information and move them to the Operator Guide and the Reference section respectively.

This issue tracks recommended changes resulting from an analysis of the KEDA documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/assessments/0011-keda/

Use-Case

The conceptual overview (also variously called a technical overview or architectural overview depending on the product) describes how the product works at a high level. It does not go into detail (for example, it might use pseudo-code; providing syntax is not the point here); rather, it tries to help the user build a mental model of the product's architecture and subsystems so that tasks and reference information will "make sense" and "stick" when the reader goes on to use the product.

Specification

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

• KEDA Concepts
  • What is KEDA?
  • How KEDA works
  • KEDA Architecture
  • KEDA Custom Resources (CRDs)
  • Scaling Deployments, StatefulSets and Custom Resources
    • Overview
    • Scaling Deployments and Stateful Sets
    • Scaling Custom Resources
    • Scaling Jobs
    • Authentication
    • External Scalers
    • Admission Webhooks

[mhmohona]

Hello! May I work on this issue?

[tomkerkhove]

Certainly!

[mhmohona]

Thank you @tomkerkhove!

@dwelsch-esi, before start working on this issue, I want to clarify some points.
I see in KEDA Concepts page,there is these sections available -

• What is KEDA?
• How KEDA works
• KEDA Architecture
• KEDA Custom Resources (CRDs)

However, there is another two sections -

1. Event sources and scalers
2. Deploy KEDA are

Shall I remove them? Or should I move it to another page? Or just leave them at the bottom of concept page?

For Scaling Deployments, StatefulSets and Custom Resources section -

• Scaling Jobs
• Authentication
• External Scalers
• Admission Webhooks

These pages are too big to move them inside Scaling Deployments, StatefulSets and Custom Resources page, then shall I just have a small pera about them and then put link to their pages?

[dwelsch-esi]

@mhmohona Good questions. Below are a couple of general comments, then responses to your questions.

General comment 1: My outline and suggested improvements are guidelines. Don't follow them to the letter if you see a better way. The important thing is to create an overview that introduces KEDA to new users, explains what it's for, outlines its architecture, and describes its components. Just rearranging the existing material might not be sufficient. You should feel free to revise any parts that you don't think are clear, and write new sections if you think something is missing.

General comment 2: The links you provide are to the 2.13 version of KEDA. It's probably best to work with the most recent published version and/or the upcoming release.

On to your questions:

"Event sources and scalers" IMO should be a reference page. Readers don't need a list of scalers to understand the product; a couple of examples should suffice. I'd describe what a scaler is, give an example, and link to the full list in case they're curious.

"Deploy KEDA" is a link to instructional information about how to get started. That information is included in the main table of contents. I'd leave it out of a conceptual overview, so yes, you can remove this section.

I wouldn't try and fit everything on one page. In fact, I'd try to keep to one page = one topic. My outline is meant to show the information structure for the conceptual overview and not to literally define the pages. I'd probably write this part in a series of separate pages, one page per topic, then link them into a sequence (with "previous" and "next" buttons at the bottom – the doc framework might even do that automatically). Also have a top-level landing page where you can access any of the page from a list of links. (So yes, your suggestion to include a short paragraph about each one and link to their pages is the right idea IMO 😄 ).

/cc @tomkerkhove