cncf
/
techdocs
mirror of https://github.com/cncf/techdocs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #77 from chalin/chalin-assessment-criteria-update-2021-10-28 

Assessment criteria & template update
This commit is contained in:
Celeste Horgan 2021-10-28 13:03:25 -07:00 committed by GitHub
parent ceb09c6d92 201c43b96d
commit 319b638ce3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 89 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
assessments/criteria.md
View File

@ -34,27 +34,27 @@ New users are the most avid users of documentation, and need content specificall
Examples: Examples:
* https://falco.org/docs/getting-started/ * https://falco.org/docs/getting-started/
## Content maintainability & site mechanics ## 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: We evaluate on the following:
* Is your documentation searchable? * Is your documentation searchable?
* Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? * 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: Examples:
* https://kubernetes.io/docs/ * https://kubernetes.io/docs/
## Content creation processes ## 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: We evaluate on the following:
@ -66,17 +66,17 @@ We evaluate on the following:
Examples: Examples:
* https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly documented maintainers) * 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 ## 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: 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? * 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 # Contributor documentation
@ -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 Slack/Discord/Discourse/etc. community and is it prominently linked from your website?
* Is there a direct link to your GitHub organization/repository? * 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 weekly/monthly project meetings documented? Is it clear how someone can join those meetings?
* Are mailing lists documented? * Are mailing lists documented?
Examples: Examples:
* https://prometheus.io/community/ * https://prometheus.io/community/
## Beginner friendly issue backlog ## Beginner friendly issue backlog
@ -120,15 +120,15 @@ We evaluate on the following:
Examples: Examples:
* https://github.com/helm/community * https://github.com/helm/community
## Project governance documentation ## 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: We evaluate on the following:
* Is project governance clearly documented? * Is project governance clearly documented?
Examples: Examples:
@ -136,29 +136,71 @@ Examples:
# Website # Website
## Branding ## Single-source requirement
CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing. Source files for _all website pages_ should reside in a _single_ repo.
Otherwise, having source files in two places will confuse contributors (who
won't know which file(s) to update) and you'll run the risk of losing updates
— [as has happened already][otel-changes-lost].
Ideally, all website files should be in the **website repo** itself.
Alternatively, files should be brought into the website repo via [git
submodules][].
If a project chooses to keep source files in multiple repos, they need a clearly
documented strategy for managing mirrored files and new contributions.
[otel-changes-lost]: https://github.com/open-telemetry/opentelemetry.io/issues/673
[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
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: We evaluate on the following:
* Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? * Is there an easily recognizable brand for the project (logo + color scheme)
* Is the brand used across the website consistently? clearly identifiable?
* Is the brand used across the website consistently?
* Is the website’s typography clean and well-suited for reading? * Is the website’s typography clean and well-suited for reading?
Examples: Examples:
* https://helm.sh/ * https://helm.sh/
## Case studies/social proof ## 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: We evaluate on the following:
* Are there case studies available for the project and are they documented on the website? * Are there case studies available for the project and are they documented on the website?
* Are there user testimonials available? * 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? * Are there community talks for the project and are they present on the website?
* Is there a logo wall of users/participating organizations? * Is there a logo wall of users/participating organizations?
@ -174,11 +216,17 @@ Website maintenance is an important part of project success, especially when pro
We evaluate on the following: 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 you actively cultivating website maintainers from within the community?
* Are site build times reasonable? * Are site build times reasonable?
* Do site maintainers have adequate permissions? * Do site maintainers have adequate permissions?
Examples: Examples:
* http://kubernetes.io * http://kubernetes.io
## Other
* Is your website accessible via HTTPS?
* Does HTTP access, if any, redirect to HTTPS?

30
assessments/template.md
View File

@ -1,4 +1,4 @@
# Assessment template # Assessment template
Prepared by: `Name` Prepared by: `Name`
Date: `Date` Date: `Date`
@ -12,13 +12,13 @@ This document:
- Measures existing documentation quality against the CNCF’s standards - Measures existing documentation quality against the CNCF’s standards
- Recommends specific and general improvements - 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 - Identifies key improvements with the largest return on investment
## How this document works ## 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 - **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 - **Contributor documentation:** for new and existing contributors to the project
@ -27,7 +27,7 @@ The assessment is divided into three sections:
Each section rates content based on different [criteria](criteria.md). Each section rates content based on different [criteria](criteria.md).
## Project documentation ## Project documentation
| Criteria | 1 | 2 | 3 | 4 | 5 | | Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
@ -36,7 +36,7 @@ Each section rates content based on different [criteria](criteria.md).
| Content maintainability | | | | | | | Content maintainability | | | | | |
| Content creation processes | | | | | | | Content creation processes | | | | | |
Scale: Scale:
- 1 = (Is not present or requires significant work) - 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work) - 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required) - 5 = (Is executed extremely well or no improvement required)
@ -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_ _Provide a list of recommendations to improve in this area_
## Contributor documentation ## Contributor documentation
| Criteria | 1 | 2 | 3 | 4 | 5 | | Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
@ -59,7 +59,7 @@ _Provide a list of recommendations to improve in this area_
| “New contributor” getting started content | | | | | | | “New contributor” getting started content | | | | | |
| Project governance documentation | | | | | | | Project governance documentation | | | | | |
Scale: Scale:
- 1 = (Is not present or requires significant work) - 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work) - 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required) - 5 = (Is executed extremely well or no improvement required)
@ -75,13 +75,17 @@ _Provide a list of recommendations to improve in this area_
## Website ## Website
| Criteria | 1 | 2 | 3 | 4 | 5 | | Criteria | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| Branding and design | | | | | | | Single-source for all files | | | | | |
| Case studies/social proof | | | | | | | Branding and design | | | | | |
| Maintenance planning | | | | | | | Case studies/social proof | | | | | |
| Maintenance planning | | | | | |
| A11y plan & implementation | | | | | |
| Mobile-first plan & impl. | | | | | |
| HTTPS access & HTTP redirect | | | | | |
Scale: Scale:
- 1 = (Is not present or requires significant work) - 1 = (Is not present or requires significant work)
- 3 = (Is present, but needs work) - 3 = (Is present, but needs work)
- 5 = (Is executed extremely well or no improvement required) - 5 = (Is executed extremely well or no improvement required)