cncf
/
techdocs
mirror of https://github.com/cncf/techdocs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
techdocs/analyses/0011-keda/keda-implementation.md

13 KiB
Raw Blame History

title
Implementing KEDA Doc Improvements

Introduction

This document provides actionable suggestions for improving the KEDA technical documentation.

For an analysis and general discussion of recommendations on KEDA technical documentation, see keda-analysis.md.

Recommendations, requirements, and best practices

This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how to apply those best practices. In other words, borrowing terminology from the lexicon of RFCs, the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues.

The documentation recommendations for this project are:

Reorganize the Table of Contents

Reorganize the Table of Contents to:

  • Better welcome and orient new users
  • Separate user rules (personas), if there are more than one
  • Improve the ease of finding and accessing tasks and procedures
  • Separate conceptual, task, and reference information

In general, follow these principles when reorganizing the documentation:

  • Put architecture, operating principles, and other conceptual explanations in the technical overview.
  • Write instructions (in "Using KEDA" and "Getting Started") as step-by-step procedures. Title each procedure using "-ing" verbs; for example "Integrating", "Using", "Migrating".
  • Put purely reference information in the Reference section. Link to this information where relevant from the procedures in the "Using KEDA" and "Getting Started" sections.
  • Separate and/or label information, especially tasks, by which user role it pertains to (again, if more than one).
  • Include a clear starting point and ramp-up path for new users.

Here is a proposed outline for the tech doc Table of Contents:

Among other things, the reorganization includes these changes:

  • Rename "The KEDA Documentation" to "Getting Started".
  • Create a "Reference" topic at the end of the ToC.
  • Move the FAQ to the Reference section.
  • Add a glossary to the Reference section.
  • Rename "Operate" to "Operator Guide".
  • Move "Troubleshooting" to the end of the User Guide.
  • Separate reference and task information that appears on the same page and move each to the appropriate section.

Write a Glossary

Create a glossary of terms specific to KEDA. Add to the Reference section.

Add "How to set up a scaler" to the Operator guide

Setting up a scaler seems to be largely a matter of installing the scaler and providing parameters in a configuration file. While the configurations are provided for all the various scalers, there doesn't seem to be a description of the procedure for doing the basic setup. This should go at the top of the Operator guide. Users should be able to follow the procedure for any (or at least most) scalers.

Any scaler that requires special instructions other than the configuration file should have its own procedure page, listing the extra steps required.

Write a New User workflow

Write a task-based, step-by-step workflow for new users. Assume the new user has no experience with KEDA and is fairly new to Kubernetes.

The current documentation assumes that users know how to deploy and use Kubernetes Custom Resources, and that using KEDA is a matter of knowing the right configuration parameters and deploying the right resources. This might be true for veteran users, but new users want explicit, foolproof instructions. The following outline, extracted from the proposed outline in Reorganize the Table of Contents, has been annotated to illustrate this point:

Update the doc content creation instructions

In the keda-docs README:

  • Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial offering!" sections into their own files, or move them to the bottom of the README, so they're not at the top of the keda-docs README.
  • Combine "Adding scaler documentation" and "Writing documentation for a scaler" so that they're not separated by "Writing documentation for a new authentication provider".

Document in the repo (keda-docs, keda, or both) who the website/documentation maintainers are.

Remove non-inclusive language

Remove non-inclusive language throughout the documentation as recommended by the Inclusive Naming Initiative.

Make user roles explicit

KEDA seems to have only one explicit user role (or persona), namely, an Operator using KEDA to scale resources on a Kubernetes installation. Regardless, this user role should be explicitly distinguished from the project Contributor user role. Use cases are different between the two roles. One strategy for separating the documentation is to confine the Contributor docs to the GitHub repo.

The definition of the Operator role could be as minimal as a "who should use this documentation" paragraph in the product introduction.

Clarify documentation maintainers

Create an OWNERS.md file to document (on the repo) the current custodian(s) of the following accounts: analytics (GA4), site-search (Algolia).

Explicitly list and solicit maintainers and contributors for documentation, either in the new OWNERS file or the governance MAINTAINERS file.