Merge pull request #229 from dwelsch-esi/analysis-howto

Revised TechDoc Analysis Tools

.prettierignore

@@ -6,3 +6,5 @@
 assessments
 docs
 /README.md
+
+assistance.md

README.md

@@ -1,20 +1,29 @@
-# CNCF TechDocs office hours
+# CNCF TechDocs
 
-This repository holds team information and meeting notes for tech docs office hours.
+This repository holds resources provided by the CNCF Technical Documentation team. The repo contains the following directories:
+
+- `analysis` contains instructions, templates, and criteria for requesting and performing an analysis of an OSS project's website and technical documentation. Completed analyses are stored here as well.
+- `resources` contains information that OSS teams can use to set up a documentation project as suggested by the TechDocs team.
 
 ## CNCF TechDocs team
 
-GitHub ID | Role
----|---
-[@chalin](https://github.com/chalin) | Senior technical writer
-[@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer
-[@thisisobate](https://github.com/thisisobate) | Developer advocate
+The full-time staff of the CNCF Tech Docs team is:
+
+| GitHub ID                                          | Role                                  |
+|----------------------------------------------------|---------------------------------------|
+| [@chalin](https://github.com/chalin)               | Senior technical writer               |
+| [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer |
+| [@thisisobate](https://github.com/thisisobate)     | Developer advocate                    |
+
+<!-- cSpell:ignore chalin nate thisisobate -->
+
+Various consultants and volunteers also contribute to CNCF Tech Docs projects.
 
 ## Office hours
 
-The CNCF tech docs team generally holds office hours on the [fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours).
+The CNCF tech docs team holds office hours on the [fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours).
 
-Office hours started on 30 September, 2020.
+Office hours started on 30 September 2020.
 
 ### Meeting link
 
@@ -24,4 +33,12 @@ Zoom link: https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?pas
 
 We store ongoing meeting notes in a [Google doc](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/).
 
-<!-- cSpell:ignore chalin nate thisisobate -->
+## Assistance program for technical documentation
+
+The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][].
+
+[assistance-program]: ./assistance.md
+
+### Resources
+
+The `docs/` directory contains collected resources for building websites and developing documentation, including recommended tools and practices, how-tos, and evaluation checklists.

assessments/README.md

@@ -0,0 +1,34 @@
+# CNCF TechDocs Analysis for OSS Projects
+
+## Purpose
+
+The goals of a CNCF technical documentation analysis are to:
+
+- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](../docs/analysis/criteria.md).
+- Compare the documentation against the current or proposed maturity level for the overall project.
+- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](../docs/analysis/resources/implementation-template.md) and [issues backlog](../docs/analysis/resources/umbrella-issue-template.md).
+
+## Audience
+
+Analyses are written for the purpose of improving a project's documentation and are available for anyone to read. Among the intended benefits to project stakeholders are these:
+
+- **Project maintainers** can gain a critical overview of the technical documentation to plan work on the project's documentation. This work can increase the effectiveness of the project software, speed adoption, and improve user satisfaction.
+- **Project contributors** can take on the recommended backlog issues to improve the documentation.
+
+The analyses also provide information of value to organizations with an interest in promoting open source software:
+
+- **CNCF Foundation members** can see what benefits can (and cannot) be expected of a documentation improvement effort.
+- **Members of other open-source software foundations** can use these analyses as a model for their own documentation improvement processes. (Please contact the Cloud Native Computing Foundation to discuss licensing and permission of analysis templates and tools.)
+
+## Contents
+
+This directory contains completed analyses of the technical documentation for selected CNCF incubating and graduated software projects. 
+
+The analyses are in one of two formats depending on when they were written. Earlier analyses (**0001** - **0007**) are Markdown files, each of which is the sole artifact of the analysis.
+
+Subsequent analyses (**0008-** forward) each has its own directory containing three analysis artifacts:
+  - `projectname-analysis.md` evaluates the project documentation and provides comments and recommendations in a manner very similar to the Round 1 tech doc assessments. This document is based on the analysis template and accompanying criteria developed for the Round 1.
+  - `projectname-implementation.md` provides concrete actions that can be implemented by project contributors. Its focus is on specific, achievable work that will have a strong positive impact on document effectiveness.
+  - `projectname-issues.md` is a backlog of improvement actions, meant to be entered as GitHub Issues, derived from `projectname-implementation.md`.
+
+Each directory might also contain other documents, such as CSV-formatted surveys of documentation pages.

assistance.md

@@ -0,0 +1,53 @@
+# Assistance program for technical documentation
+
+This document outlines the Cloud Native Computing Foundation (CNCF) Technical Documentation Assistance Program (the Program), a service offered by CNCF Tech Docs for evaluating and improving an OSS project's technical documentation. The process is designed to:
+
+1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](docs/analysis/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level.
+1. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project.
+1. Expand on the recommended changes in an implementation plan.
+1. Break down the implementation into a documentation project backlog comprising a GitHub Issues list.
+1. Support the project team's contributors in taking up and completing the issue backlog items.
+1. Leave the project team with an improved understanding and skill base for improving and maintaining the project documentation.
+
+## Phase 0: Training
+
+Some level of familiarity with the technical documentation process is required to:
+
+- Work effectively with technical writers
+- Draft technical documentation (for non-writers)
+- Get the best results out of the Assistance Program
+
+For this reason, CNCF offers free training on documentation essentials for project contributors and maintainers. To get the most from the Assistance Program, project contributors are encouraged to do the training *before* engaging a documentation specialist to complete the documentation analysis.
+
+The training program consists of the following online courses. Anyone can sign up for and complete the courses at their own pace.
+
+1. [Open Source Technical Documentation Essentials (LFC111)](https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/)
+1. [Creating Effective Documentation for Developers (LFC112)](https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/)
+
+## Phase 1: Documentation analysis
+
+A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed as part of the CNCF TechDocs program, the writer:
+
+1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project using a rubric developed by CNCF. The rubric is divided into three categories:
+    1. Project documentation: The end-user documentation for the project's work product, typically (but not always) an application, API, protocol, or some other software product.
+    1. Contributor documentation: Documentation about the project, aimed at project contributors and describing procedures, infrastructure, and customs for doing project work. This includes artifacts that define procedures and governance; recruit, orient, and train project contributors; and name responsible parties (project leaders, often generically called *maintainers*).
+    1. Website: The technical infrastructure behind the documentation and the project's web presence, including website generation, versioning, SEO, analytics, and security.
+1. Collaborates with project leadership to identify user roles and objectives for software users.
+1. Proposes changes, if necessary, to the organization and content of the documentation to close gaps with the target maturity level.
+1. Writes an implementation plan describing improvements that address the gaps identified by the analysis.
+
+## Phase 2: Backlog creation
+
+Once a high-level improvement plan has been written and approved, the tech writer analyzes the proposed changes to create a backlog of actionable, individual writing assignments and other tasks to improve the documentation. These tasks should have two primary characteristics:
+- As much as possible, they should be independent of each other so they can be completed in any order by any combination of contributors; and
+- They should be time-constrained. If possible, large tasks should be broken down into smaller, independent tasks that require hours or days rather than weeks to complete.
+
+## Phase 3: Documentation improvement
+
+Community members work on the issues created in the previous phase. Ideally, tech writers are available to advise contributors and edit work, especially if the contributing community members are not trained technical writers. Remember that the training courses in Phase 0 are available to prepare contributors with general knowledge of the process.
+
+We know that recruiting contributors to write documentation can be difficult. While this is largely the responsibility of the project leadership, CNCF is actively working on ways to encourage doc contributions. For example, creating a backlog of time-bounded issues is an attempt to lower barriers, both psychological and logistical, to documentation creation and maintenance.
+
+## Phase 4: Impact analysis
+
+Projects are encouraged to collect metrics (using Google analytics and page feedback data) on documentation usage as a means of assessing the effectiveness of documentation improvements.

docs/analysis/README.md

@@ -0,0 +1,10 @@
+# TechDoc Analysis
+
+## Contents
+
+This directory contains instructions and criteria for completing a documentation analysis, including a [how-to][] guide and analysis [criteria][].
+
+Templates for the analyses are in the resources directory.
+
+[how-to]: ./howto.md
+[criteria]: ./criteria.md