Completed first draft of tech doc analysis READMEs, instructions, and…

… templates. Reorganized tech-docs directory structure.

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

analysis/README.md

@@ -1,48 +1,71 @@
 # CNCF TechDocs Analysis for OSS Projects
 
-This directory contains:
+## Purpose
 
-- Analyses of the technical documentation for selected CNCF incubating and graduated software projects. 
-- Tools (templates, analysis criteria, background information) to enable a mid- to senior-level technical writer to perform an analysis independently with some support from the CNCF tech docs staff. 
+The goals of a CNCF technical documentation analysis are to:
 
-## Project Analyses
+- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](./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](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md).
 
-There are two rounds of projects:
+## Contents
 
-1. Analyses **0001** - **0007** are a first round of projects completed as "assessments" through the CNCF Help Desk. The file `000N-projectname.md` file is the sole artifact of the assessment in each case. The last one was added in May 2023.
-2. Subsequent analyses were commissioned starting in November 2023. Each has its own directory, `00NN-projectname`, containing three analysis artifacts:
-  - `projectname-analysis.md` evaluates the project documentation and provides comments and recommendations in a manner very similar to the first round of tech doc assessments. This document is based on the analysis template and accompanying criteria developed for the first round.
+In this directory:
+
+- **Project Analyses**: `analysis` contains analyses of the technical documentation for selected CNCF incubating and graduated software projects. 
+- **Analysis Tools**: `analysis-tools` contains instructions, templates, analysis criteria, and background information to enable a mid- to senior-level technical writer to perform an analysis independently with some support from the CNCF tech docs staff. 
+
+### Project Analyses
+
+Completed analyses are contained in the `analysis` directory.
+
+There are two rounds of projects, *Round 1* and *Round 2*.
+
+#### Round 1
+
+Analyses **0001** - **0007** are a first round of projects completed as "assessments" through the CNCF Help Desk. The `000N-projectname.md` file is the sole artifact of the assessment in each case. The last one was added in May 2023.
+
+#### Round 2
+
+Subsequent analyses were commissioned starting in November 2023. Each has its own directory, `00NN-projectname`, 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`.
 
-## Analyst Tools
+### Analysis Tools
 
-Read and follow the guidelines in the `analyst-tools` directory to perform a documentation analysis for CNCF. These guidelines provide:
-- A relatively objective set of criteria (a "rubric") for evaluating technical documentation.
-- An attempt the documentation analysis to the current (or proposed) maturity level for the overall project.
-- A consistent set of criteria on which to evaluate existing documentation and website content, infrastructure, and support.
-- Emphasis on effective documentation that serves all users associated with the project.
+Templates and instructions for doing the analyses are contained in the `analysis-tools` directory.
 
-### How-to
+#### Audience
 
-This document contains a general discussion of the CNCF Tech Docs analysis program and instructions for requesting, writing, and consuming an analysis.
+This directory is for primarily for members of the CNCF TechDocs team, including contractors or consultants, who need to conduct or assist with an analysis of a CNCF open-source project's technical documentation. Readers in other roles can also benefit from understanding the guidelines in this directory:
 
-### Criteria
+- **Project maintainers** can learn how improved technical documentation can increase the effectiveness of the project software, speed adoption, and improve user satisfaction.
+- **CNCF Foundation members** can learn what benefits can (and cannot) be expected of a documentation improvement effort.
+- **Members of other open-source software foundations** can use the analysis tools as a model, in whole or in part, for their own documentation improvement processes. (Please contact the Cloud Native Computing Foundation to discuss licensing and permission.)
+- **Project contributors** can learn what factors go into improving technical documentation and what is expected of contributors who work on project documentation issues.
 
-This document describes the criteria used to evaluate a project's technical documentation and website. These criteria are also referred to as a "rubric" elsewhere in this repo.
+#### Contents
 
-### Templates
+Use the guidelines and templates in this directory to perform a documentation analysis for CNCF. These materials provide:
+- A relatively objective set of criteria (a "rubric") for evaluating existing documentation and website content, infrastructure, and support.
+- An attempt to make the documentation analysis appropriate to the current (or proposed) maturity level for the overall project.
+- Emphasis on effective documentation that serves all users associated with the project.
 
-These are templates for the analysis artifacts.
+##### How-to
 
-#### Analysis Template
+`howto.md` contains instructions for requesting, writing, and consuming an analysis.
 
-This is the main analysis template, based on the work of the original 2021-23 tech docs assessments. 
+##### Criteria
 
-#### Implementation Plan
+`criteria.md` describes the criteria used to evaluate a project's technical documentation and website. These criteria are also referred to as a "rubric" elsewhere in this repo. The criteria are unchanged between the first and second round of analyses.
 
-The implementation plan is an intermediate step between the analysis and the issues backlog, meant as an aid to digesting the analysis recommendations into actionable issues. 
+##### Templates
 
-#### Issues
+These are templates for the analysis artifacts.
 
-This is the final backlog of recommended changes to the documentation, meant to be transferred more or less directly into the GitHub Issues of the project documentation repo.
+- **Analysis Template**: `analysis-template.md` is the main analysis template, based on the work of the original 2021-23 tech docs assessments. 
+- **Implementation Plan**: The implementation plan, represented in `implementation-template.md`, is an intermediate step between the analysis and the issues backlog, meant as an aid to digesting the analysis recommendations into actionable issues. 
+- **Issues**: This is the final backlog of recommended changes to the documentation, meant to be transferred directly into the GitHub Issues of the project documentation repo. There are two templates:
+    - `issue-template.md` is a template for individual issues that can be use to create issues in GitHub.
+    - `umbrella-issue-template.md` can be used to create an umbrella issue in GitHub, and can also be used as a template for a `_PROJECT_-issues.md` document to be included in the analysis pull request.