KEDA Docs Assessment - DRAFT

Prepared by: Uche (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.

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