1.6 KiB
CNCF Project documentation assessments
Who this document is for: Members of the CNCF Techdocs team. This document provides guidance and a template on executing documentation assessments for CNCF projects.
Purpose
The aim of a documentation assessment is to:
- Measure against the CNCF’s standards for documentation
- Recommend areas to improve
- Provide examples of great documentation as reference
- Identify key areas which will net the largest improvement if addressed
What an assessment is
- An overview with specific recommendations
- As short as possible – err on the side of bulleted lists
- Geared at providing actionable feedback (litmus test: could you turn a piece of feedback into a backlog issue with little extra work?)
What it isn’t
- Full lists of exhaustive solutions for each and every issue with a website
- Fluffy and unspecific
- Judgmental
Assessment criteria and examples
See Assessment definitions and reference examples.
Doing an assessment
When doing an assessment:
-
Locate a project’s main documentation repository and any community/contributor/org/governance repositories Review all documentation available & the website (if present).
-
Note:
- Any quick wins
- Larger, systemic issues at play
- Main issues to fix
- What the project does exceptionally well!
-
Draft the assessment using the template provided
-
Send it to the CNCF techdocs team for a review
-
Send it to the project maintainers and schedule a zoom meeting to discuss with them in person.
-
PR to the techdocs repository in this directory for archiving