-
Notifications
You must be signed in to change notification settings - Fork 426
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
Comments
Hello! May I work on this issue? |
Certainly! |
Thank you @tomkerkhove! @dwelsch-esi, before start working on this issue, I want to clarify some points.
However, there is another two sections - 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? |
@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 |
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.
The text was updated successfully, but these errors were encountered: