You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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 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
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.
stalebot
added
the
stale
All issues that are marked as stale due to inactivity
label
Jun 15, 2024
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:
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.
externalscaler.proto
and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently.The text was updated successfully, but these errors were encountered: