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

54
assessments/criteria.md
View File

@ -136,13 +136,55 @@ Examples:
# Website
## 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?
[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.
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 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?
@ -174,7 +216,8 @@ 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?
@ -182,3 +225,8 @@ We evaluate on the following:
Examples:
* http://kubernetes.io
## Other
* Is your website accessible via HTTPS?
* Does HTTP access, if any, redirect to HTTPS?

14
assessments/template.md
View File

@ -75,11 +75,15 @@ _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 | | | | | |
| 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)