Merge pull request #10 from celestehorgan/add-assessments-docs

Add documentation assessments information

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 

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
+

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_
+
+
+
+