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

Separate reference and task information #1370

Open
9 tasks
Tracked by #1361 ...
dwelsch-esi opened this issue Apr 15, 2024 · 2 comments
Open
9 tasks
Tracked by #1361 ...

Separate reference and task information #1370

dwelsch-esi opened this issue Apr 15, 2024 · 2 comments
Labels
cant-touch-this All issues that should not be automatically closed by our stale bot

Comments

@dwelsch-esi
Copy link
Contributor

In pages where conceptual, reference, and/or task info appears on the same page, separate and move each to the appropriate section.

Use-Case

Mixing conceptual and task information is unfortunately a common practice that reduces documentation effectiveness. 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 self-contained and therefore easy to extract.

Here's a quick guide to the three main types of information that appear in software product technical documentation:

Type Definition KEDA Example Notes
Conceptual Explanatory material KEDA Concepts Gives the reader a mental schema of the product: its architecture and overall workflow.
Task Procedures for installing and using the product Deploying KEDA Tells the reader how to use the product: instructions, procedures, recipes.
Reference For looking things up Scalers Where the reader goes to look something up when they need to choose between options, see a syntax example, and so on.

Specification

Here is a checklist 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.

  • Deploying KEDA: 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 Resources: The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task.
  • Scaling Jobs: "ScaledJob spec" is reference information.
  • 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 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.
  • Troubleshooting: Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation".
  • Cluster: See the "Update the Operator Guide" issue
  • Events: This is reference information.
  • Integrate with Prometheus: Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus".
Copy link

stale bot commented Jun 15, 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 Jun 15, 2024
@nate-double-u
Copy link
Contributor

nate-double-u commented Jun 18, 2024

It's best not to auto-delete this issue; it is still relevant.

@stale stale bot removed the stale All issues that are marked as stale due to inactivity label Jun 18, 2024
@tomkerkhove tomkerkhove added the cant-touch-this All issues that should not be automatically closed by our stale bot label Jun 19, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cant-touch-this All issues that should not be automatically closed by our stale bot
Projects
Status: No status
Development

No branches or pull requests

3 participants