Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Assessment criteria & template update #77

Merged
merged 3 commits into from
Oct 28, 2021
Merged

Assessment criteria & template update #77

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
def0058
Assessment criteria & template update
chalin Oct 28, 2021
0a262f4
Update assessments/criteria.md
chalin Oct 28, 2021
201c43b
Single-source req text rework
chalin Oct 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 63 additions & 24 deletions assessments/criteria.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,27 +34,27 @@ New users are the most avid users of documentation, and need content specificall

Examples:

* https://falco.org/docs/getting-started/
* https://falco.org/docs/getting-started/


## Content maintainability & site mechanics

As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them.
As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them.

We evaluate on the following:

* Is your documentation searchable?
* Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present?
* Do you have a clearly documented method for versioning your content?
* Do you have a clearly documented method for versioning your content?



Examples:

* https://kubernetes.io/docs/
* https://kubernetes.io/docs/

## Content creation processes

Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code.
Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code.

We evaluate on the following:

Expand All @@ -66,17 +66,17 @@ We evaluate on the following:
Examples:

* https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly documented maintainers)
* https://thanos.io/tip/contributing/how-to-contribute-to-docs.md/
* https://thanos.io/tip/contributing/how-to-contribute-to-docs.md/


## Inclusive language

Creating inclusive project communities is a key goal for all CNCF projects.
Creating inclusive project communities is a key goal for all CNCF projects.

We evaluate on the following:

* Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website?
* Does the project use language like "simple", "easy", etc.?
* Does the project use language like "simple", "easy", etc.?

# Contributor documentation

Expand All @@ -88,12 +88,12 @@ We evaluate on the following:

* Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?
* Is there a direct link to your GitHub organization/repository?
* Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings?
* Are mailing lists documented?
* Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings?
* Are mailing lists documented?

Examples:

* https://prometheus.io/community/
* https://prometheus.io/community/

## Beginner friendly issue backlog

Expand All @@ -120,45 +120,78 @@ We evaluate on the following:

Examples:

* https://github.com/helm/community
* https://github.com/helm/community

## Project governance documentation

One of the CNCF’s core project values is open governance.
One of the CNCF’s core project values is open governance.

We evaluate on the following:

* Is project governance clearly documented?
* Is project governance clearly documented?

Examples:

* Any graduated CNCF project

# Website

## Branding
## Single-source requirement

Source files for _all website pages_ should reside in a single repo, ideally in
the website repo itself, otherwise be brought into the website repo via [git
submodules][]. This avoids having source files in two places,
chalin marked this conversation as resolved.
Show resolved Hide resolved

[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules

## Usability, accessibility and devices

Most CNCF websites are accessed from mobile and other non-desktop devices at
least 10-20% of the time. Planning for this early in your website's design will
be much less effort than retrofitting a desktop-first design.

* Is the website usable from mobile?
* Are doc pages readable?
* Are all / most website features accessible from mobile -- such as the top-nav,
site search and in-page table of contents?
* Might a [mobile-first] design make sense for your project?

[mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first

CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing.
Plan for suitable [accessibility][] measures for your website. For example:

* Are color contrasts significant enough for color-impaired readers?
* Are most website features usable using a keyboard only?
* Does text-to-speech offer listeners a good experience?

It is up to each project to set their own guidelines.

[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility
## Branding

CNCF seeks to support enterprise-ready open source software. A key aspect of
this is branding and marketing.

We evaluate on the following:

* Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable?
* Is the brand used across the website consistently?
* Is there an easily recognizable brand for the project (logo + color scheme)
clearly identifiable?
* Is the brand used across the website consistently?
* Is the website’s typography clean and well-suited for reading?

Examples:

* https://helm.sh/
* https://helm.sh/

## Case studies/social proof

One of the best ways to advertise an open source project is to show other organizations using it.
One of the best ways to advertise an open source project is to show other organizations using it.

We evaluate on the following:

* Are there case studies available for the project and are they documented on the website?
* Are there user testimonials available?
* Is there an active project blog?
* Is there an active project blog?
* Are there community talks for the project and are they present on the website?
* Is there a logo wall of users/participating organizations?

Expand All @@ -174,11 +207,17 @@ Website maintenance is an important part of project success, especially when pro

We evaluate on the following:

* Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?)
* Is your website tooling well supported by the community (i.e., Hugo with the
Docsy theme) or commonly used by CNCF projects (our recommended tech stack?)
* Are you actively cultivating website maintainers from within the community?
* Are site build times reasonable?
* Do site maintainers have adequate permissions?

Examples:

* http://kubernetes.io
* http://kubernetes.io

## Other

* Is your website accessible via HTTPS?
* Does HTTP access, if any, redirect to HTTPS?
chalin marked this conversation as resolved.
Show resolved Hide resolved
32 changes: 18 additions & 14 deletions assessments/template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Assessment template
# Assessment template

Prepared by: `Name`
Date: `Date`
Expand All @@ -12,13 +12,13 @@ This document:

- Measures existing documentation quality against the CNCF’s standards
- Recommends specific and general improvements
- Provides examples of great documentation as reference
- 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:
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
Expand All @@ -27,7 +27,7 @@ The assessment is divided into three sections:
Each section rates content based on different [criteria](criteria.md).


## Project documentation
## Project documentation

| Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- |
Expand All @@ -36,7 +36,7 @@ Each section rates content based on different [criteria](criteria.md).
| Content maintainability | | | | | |
| Content creation processes | | | | | |

Scale:
Scale:
- 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required)
Expand All @@ -50,7 +50,7 @@ _Provide comments for each rating above, 1-2 sentences max, bullet point list_
_Provide a list of recommendations to improve in this area_


## Contributor documentation
## Contributor documentation

| Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- |
Expand All @@ -59,7 +59,7 @@ _Provide a list of recommendations to improve in this area_
| “New contributor” getting started content | | | | | |
| Project governance documentation | | | | | |

Scale:
Scale:
- 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required)
Expand All @@ -75,13 +75,17 @@ _Provide a list of recommendations to improve in this area_

## Website

| Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- |
| Branding and design | | | | | |
| Case studies/social proof | | | | | |
| Maintenance planning | | | | | |

Scale:
| Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- |
| Single-source for all files | | | | | |
| Branding and design | | | | | |
| Case studies/social proof | | | | | |
| Maintenance planning | | | | | |
| A11y plan & implementation | | | | | |
| Mobile-first plan & impl. | | | | | |
| HTTPS access & HTTP redirect | | | | | |

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