diff --git a/assessments/criteria.md b/assessments/criteria.md index b16e34a..7b277a7 100644 --- 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,15 +120,15 @@ 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: @@ -136,29 +136,71 @@ Examples: # 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 +— [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 index 7295c90..36f7295 100644 --- 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)