diff --git a/assessments/criteria.md b/assessments/criteria.md new file mode 100644 index 0000000..80f42b0 --- /dev/null +++ b/assessments/criteria.md @@ -0,0 +1,184 @@ +# Assessment criteria and examples + +# Project documentation + +## Information architecture + +The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: + +* Is there high level conceptual/“About” content? +Is the documentation feature complete? (i.e., each product feature is documented) +* Are there step-by-step instructions (tasks, tutorials) documented for features? +* Are there any key features which are documented but missing task documentation? +* Is the “happy path”/most common use case documented? +Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) +*If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) +* If the product exposes an API, is there a complete reference? +* Is content up to date and accurate? + +Examples: + +* https://prometheus.io/docs/ + + +## New user content + +New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: + +* Is “getting started” clearly labeled? (“Getting started”, “Installation”, “First steps”, etc.) +* Is installation documented step-by-step? +* If needed, are multiple OSes documented? +* Do users know where to go after reading the getting started guide? +* Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? +* Is there easily copy-pastable sample code or other example content? + +Examples: + +* 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. + +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? + + +Examples: + +* 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. + +We evaluate on the following: + +* Is there a clearly documented (ongoing) contribution process for documentation? +* Does your code release process account for documentation creation & updates? +* Who reviews and approves documentation pull requests? +* Does the website have a clear owner/maintainer? + +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/ + + +## Inclusive language + +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.? + +# Contributor documentation + +## Communication methods documented + +One of the easiest ways to attract new contributors is making sure they know how to reach you. + +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? + +Examples: + +* https://prometheus.io/community/ + +## Beginner friendly issue backlog + +We evaluate on the following: + +* Are docs issues well-triaged? +* Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? +* Are issues well-documented (i.e., more than just a title)? +* Are issues maintained for staleness? + +Examples: + +* https://github.com/opentracing/opentracing.io/issues (all of open tracing’s backlogs are well maintained!) + +## New contributor getting started content + +Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily? + +We evaluate on the following: + +* Do you have a community repository or section on your website? +* Is there a document specifically for new contributors/your first contribution? +* Do new users know where to get help? + +Examples: + +* https://github.com/helm/community + +## Project governance documentation + +One of the CNCF’s core project values is open governance. + +We evaluate on the following: + +* Is project governance clearly documented? + +Examples: + +* Any graduated CNCF project + +# Website + +## 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 the website’s typography clean and well-suited for reading? + +Examples: + +* 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. + +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? +* Are there community talks for the project and are they present on the website? +* Is there a logo wall of users/participating organizations? + +Examples: + +* https://www.fluentd.org/testimonials (user testimonials) +* https://goharbor.io/ (logo wall) +* https://blog.rook.io/ (blog) + +## Maintenance planning + +Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. + +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?) +* 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 diff --git a/assessments/howto.md b/assessments/howto.md new file mode 100644 index 0000000..7f1c798 --- /dev/null +++ b/assessments/howto.md @@ -0,0 +1,50 @@ +# 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](criteria.md). +Doing an assessment + +When doing an assessment: + +1. Locate a project’s main documentation repository and any community/contributor/org/governance repositories +Review all documentation available & the website (if present). + +2. Note: + + - Any quick wins + - Larger, systemic issues at play + - Main issues to fix + - What the project does exceptionally well! + +3. Draft the assessment using the template provided + +4. Send it to the CNCF techdocs team for a review + +5. Send it to the project maintainers and schedule a zoom meeting to discuss with them in person. + +6. PR to the techdocs repository in this directory for archiving + diff --git a/assessments/template.md b/assessments/template.md new file mode 100644 index 0000000..df6c131 --- /dev/null +++ b/assessments/template.md @@ -0,0 +1,90 @@ +# Assessment template + +## Introduction + +Prepared by: `Name` +Date: `Date` + +This is an assessment of your project documentation and website (if present), prepared for you and your project by the CNCF techdocs team. + +This document aims to: + +- Measure existing documentation quality against the CNCF’s standards +- Recommend specific and general improvements +- Provide examples of great documentation as reference +Identify key areas which will net the largest improvement if addressed + +## How this document works + +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 +- **Website:** branding, website structure, and maintainability + +Within each section you receive a rating on different criteria. The full definition of each criteria is defined in [the criteria](criteria.md). We recommend reading each criterion’s definition. + +## Project documentation + + +| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | +| --- | --- | --- | --- | --- | --- | +| Information architecture | | | | | | +| New user content | | | | | | +| Content maintainability | | | | | | +| Content creation processes | | | | | | + +**Comments** + +_Provide comments for each rating above, 1-2 sentences max, bullet point list_ + +**Recommendations** + +_Provide a list of recommendations to improve in this area_ + +## Contributor documentation + + +| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | +| --- | --- | --- | --- | --- | --- | +| Communication methods documented | | | | | | +| Beginner friendly issue backlog | | | | | | +| “New contributor” getting started content | | | | | | +| Project governance documentation | | | | | | + +**Comments** + +_Provide comments for each rating above, 1-2 sentences max, bullet point list_ + +**Recommendations** + +_Provide a list of recommendations to improve in this area_ + + +## Website + + +| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | +| --- | --- | --- | --- | --- | --- | +| Branding and design | | | | | | +| Case studies/social proof | | | | | | +| Maintenance planning | | | | | | + +**Comments** + +_Provide comments for each rating above, 1-2 sentences max, bullet point list_ + +**Recommendations** + +_Provide a list of recommendations to improve in this area_ + + +## Recommendations + +_From the recommendations above, pull out the top 1-3 concerns for this particular project and expand on them in enough detail that you could either:_ + - _Pass the work off to a contractor or other member of the CNCF techdocs team_ + - _Write a GitHub issue for the project team and place it in the backlog and someone not involved in the docs assessment process could execute on it_ + + + +