---
# System prepended metadata

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

---

---
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_

