Separate reference and task information

[dwelsch-esi]

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".

[stale]

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.

[nate-double-u]

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