Renamed directories, made recommended changes from reviews.

Signed-off-by: David Welsch <dwelsch@expertsupport.com>
Signed-off-by: Patrice Chalin <pchalin@gmail.com>

README.md

@@ -35,4 +35,10 @@ We store ongoing meeting notes in a [Google doc](https://docs.google.com/documen
 
 ## Assistance program for technical documentation
 
-The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see TechDocs [Assistance program](./TechDoc-Assistance-Program.md).
+The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][].
+
+[assistance-program]: ./techdoc-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.

analyses/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](./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).
+
+## 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.

analysis/README.md

@@ -1,71 +0,0 @@
-# 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](./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).
-
-## Contents
-
-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`.
-
-### Analysis Tools
-
-Templates and instructions for doing the analyses are contained in the `analysis-tools` directory.
-
-#### Audience
-
-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:
-
-- **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.
-
-#### Contents
-
-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.
-
-##### How-to
-
-`howto.md` contains instructions for requesting, writing, and consuming an analysis.
-
-##### Criteria
-
-`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.
-
-##### Templates
-
-These are templates for the analysis artifacts.
-
-- **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.

docs/README.md

@@ -0,0 +1,4 @@
+# CNCF Techdocs how-tos 
+
+This directory contains documentation on how the CNCF TechDocs team does things. While its intent is for the CNCF TechDocs team's use, we encourage project maintainers to use these documents if you find them helpful!
+

resources/README.md

@@ -1,4 +1,15 @@
-# CNCF Techdocs how-tos 
+# TechDoc Analysis Templates
 
-This directory contains documentation on how the CNCF TechDocs team does things. While its intent is for the CNCF TechDocs team's use, we encourage project maintainers to use these documents if you find them helpful!
+This directory contains templates for analyzing a CNCF project's documentation. 
 
+## Contents
+
+Use the 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.
+
+Resources for completing a documentation analysis, including a [how-to][] guide and analysis [criteria][], are in the `docs` directory.
+
+[how-to]: ../docs/howto.md
+[criteria]: ../docs/criteria.md

techdoc-assistance.md

@@ -2,7 +2,7 @@
 
 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](analysis/analysis-tools/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level.
+1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](docs/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.
@@ -29,7 +29,6 @@ The training program consists of the following online courses. Anyone can sign u
 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:
-2. ```
     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.
@@ -52,5 +51,3 @@ We know that recruiting contributors to write documentation can be difficult. Wh
 ## 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.
-
-As a basic gauge the effectiveness of the documentation effort, projects can track the issue backlog. This can provide a guide to progress on leveling the documentation maturity to that of the project.