Merge pull request #77 from chalin/chalin-assessment-criteria-update-…

…2021-10-28 Assessment criteria & template update
cncf · Oct 28, 2021 · 319b638 · 319b638
2 parents ceb09c6 + 201c43b
commit 319b638
Show file tree

Hide file tree

Showing 2 changed files with 90 additions and 38 deletions.
diff --git a/assessments/criteria.md b/assessments/criteria.md
@@ -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:
 
@@ -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
 
@@ -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
 
@@ -120,45 +120,87 @@ 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.
+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
+&mdash; [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?
 
-CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing. 
+[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:
 
-* 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?
 
@@ -174,11 +216,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?
diff --git a/assessments/template.md b/assessments/template.md
@@ -1,4 +1,4 @@
-# Assessment template 
+# Assessment template
 
 Prepared by: `Name`
 Date: `Date`
@@ -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
@@ -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   |
 | ---                        | --- | --- | --- | --- | --- |
@@ -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)
@@ -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   |
 | ---                                       | --- | --- | --- | --- | --- |
@@ -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)
@@ -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)