Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganize Concepts #1363

Open
Tracked by #1361 ...
dwelsch-esi opened this issue Apr 12, 2024 · 7 comments · May be fixed by #1512
Open
Tracked by #1361 ...

Reorganize Concepts #1363

dwelsch-esi opened this issue Apr 12, 2024 · 7 comments · May be fixed by #1512

Comments

@dwelsch-esi
Copy link
Contributor

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
Copy link

mhmohona commented Jun 1, 2024

Hello! May I work on this issue?

@tomkerkhove
Copy link
Member

Certainly!

@mhmohona
Copy link

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 -

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
Copy link
Contributor Author

@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

Copy link

stale bot commented Aug 26, 2024

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 stale bot added the stale All issues that are marked as stale due to inactivity label Aug 26, 2024
Copy link

stale bot commented Sep 3, 2024

This issue has been automatically closed due to inactivity.

@nate-double-u
Copy link
Contributor

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

@wozniakjan wozniakjan reopened this Nov 25, 2024
@stale stale bot removed the stale All issues that are marked as stale due to inactivity label Nov 25, 2024
@ibmgeek ibmgeek linked a pull request Dec 13, 2024 that will close this issue
1 task
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Done
Development

Successfully merging a pull request may close this issue.

5 participants