search

kedacore / keda-docs

Documentation and landing page for KEDA
https://keda.sh
Apache License 2.0
121 stars 442 forks source link

Reorganize Concepts #1363

Open dwelsch-esi opened 7 months ago

dwelsch-esi commented 7 months ago

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.

mhmohona commented 5 months ago

Hello! May I work on this issue?

tomkerkhove commented 5 months ago

Certainly!

mhmohona commented 5 months ago

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 -

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 -

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 commented 5 months ago

@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

stale[bot] commented 3 months ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. Thank you for your contributions.

stale[bot] commented 2 months ago

This issue has been automatically closed due to inactivity.

nate-double-u commented 3 weeks ago

I'm not sure this has been completed, if it was just the bot that closed this could we reopen it?