---
title: KEDA Docs Assessment - DRAFT
tags: KEDA, CNCF, docs-assessment
---

# KEDA Docs Assessment - DRAFT

Prepared by: Uche ([thisisobate](https://github.com/thisisobate))
Date: 2021-06-17

https://keda.sh/
https://github.com/kedacore/keda-docs

Note: keda.sh is a Hugo site.

## Introduction

This document assesses the quality and completeness of a project's documentation and website (if present).

This document:

- Measures existing documentation quality against the CNCF’s standards
- Recommends specific and general improvements
- Provides examples of great documentation as reference
- Identifies key improvements with the largest return on investment

## How this document works

The assessment is divided into three sections:

- **Project documentation:** for end users of the project; aimed at people who intend to use it
- **Contributor documentation:** for new and existing contributors to the project
- **Website:** branding, website structure, and maintainability

Each section rates content based on different [criteria](criteria.md).

## Project documentation

| Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- |
| Information architecture | | | x | | |
| New user content | x | | | | |
| Content maintainability | | | | x | |
| Content creation processes | | | | x | |

Scale:
- 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required)

**Comments**
* Information architecture
* The information architecture is well planned but lacks access to vital information.

* [Information architecture diagram](https://docs.google.com/drawings/d/1Guqsz3CSwB6IFA-_usSpDLAli7ET1lHDOEi0fsFeRIA/edit?usp=sharing) (proposed)

* New user content
* There is no clear direction for new users to onboard to the project. This is critical to the adoption of the project and thus requires more work.
* Content maintainability
* The site mechanics is awesome. Some vital documentation (e.g. content versioning method) already exist on GitHub. It needs to be added to the website.
* Content creation processes
* This is also a very important step in the user onboarding process. The information about the content creation process should be easily accessible by the user.

**Recommendations**

* Information architecture
* Add available scalers as nav items under the scalers nav dropdown
* Add a tutorials page for Keda; we can add it to the getting-started list.

* New user content
* Rename nav from **keda documentation** to **getting started**
* A more elaborate **getting started** page
* Create a separate installation page
* Add signpost to **getting-started** on landing page
* Content maintainability
* Add method for content versioning to docs
* Content creation processes
* Add a link to the **contributing** page on the website footer

## Contributor documentation

| Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- |
| Communication methods documented | | | | | x |
| Beginner friendly issue backlog | | | | | x |
| “New contributor” getting started content | | | x | | |
| Project governance documentation | | | | | x |

Scale:
- 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required)

**Comments**
* Communication methods documented
* Well documented!
* Beginner friendly issue backlog
* Beginner issues are properly labeled and documented; well done!
* “New contributor” getting started content
* "New contributor" documents are not properly documented.
* Project governance documentation
* Well documented.

**Recommendations**

* "New contributor" getting started content
* Rename **Get involved** signpost to **Join the community** on landing page
* Create a **how-to-contribute** document and add to the **community** submenu on website

## Website

| Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- |
| Single-source for all files | | | | | x |
| Meets min website req. (for maturity level) | | | | | x |
| Branding and design | | | | | x |
| Case studies/social proof | | | | x | |
| Maintenance planning | | | | | x |
| A11y plan & implementation | | | | x | |
| Mobile-first plan & impl. | | | | | x |
| HTTPS access & HTTP redirect | | | | | x |
| Google Analytics 4 for production only | | | | | |
| Indexing allowed for production server only | | | | | |
| Intra-site / local search | | | | | |
| Account custodians are documented | | | | | |

Scale:
- 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required)

**Comments**
* Single-source for all files
* Well done!
* Meets min website req. (for maturity level)
* Satisfies all the website requirement!
* Branding and design
* Great branding; noticeable across the website.
* Case studies/social proof
* Case studies are well documented; needs to be positioned appropriately.
* Maintenance planning
* Well documented.
* A11y plan & implementation
* Website is super accessible; needs a bit of work to make it better.
* Mobile-first plan & impl.
* Very mobile friendly; love it!
* HTTPS access & HTTP redirect
* Well done!

_Include a list of the top 404s, as reported through analytics or a search console._

**Recommendations**
* Case studies/social proof
* Testimonial should be included in the navigation menu for easy access
* A11y plan & implementation
* Show focus state on buttons
* Create an a11y plan doc to satisfy WCAG standards

## Recommendations

_From the recommendations above, lis the top 1-3 concerns for this particular project and expand on them in enough detail that you could either:_
- _Pass the work off to a contractor or other member of the CNCF techdocs team_
- _Write a GitHub issue for the project team and place it in the backlog and someone not involved in the docs assessment process could execute on it_