mirror of https://github.com/cncf/techdocs.git
Merge pull request #10 from celestehorgan/add-assessments-docs
Add documentation assessments information
This commit is contained in:
Zach Corleissen
GitHub
commit
177fd8897f
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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_
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue