From 9f2938b132519142c2ca3ce9c381c515bd108b6d Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Wed, 15 May 2024 10:46:41 -0700 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Patrice Chalin Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Patrice Chalin --- README.md | 14 +++----------- TechDoc-Assistance-Program.md | 29 +++++++++++++++-------------- 2 files changed, 18 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 57e1c37..0c421ff 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ 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 Tech Docs team. +- `resources` contains information that OSS teams can use to set up a documentation project as suggested by the TechDocs team. ## CNCF TechDocs team @@ -33,14 +33,6 @@ 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/). -## The Technical Documentation Assistance Program +## Assistance program for technical documentation -The CNCF Tech Doc team has created a program to assist CNCF-affiliated projects in creating effective documentation. [`TechDoc-Assistance-Program.md`](./TechDoc-Assistance-Program.md) contains an outline of this program. - -Project maintainers are asked to understand that: -- Project documentation resources are *always* underestimated. -- Documentation is as much a real part of a project as code. -- Effective documentation requires a real commitment of resources. -- The TechDoc Assistance Program exists to help maintainers allocate these resources effectively, but cannot write documentation for you or 'fix' documentation problems. - -We're passionate about good documentation and we want to help your project succeed. Please work with us by taking this part of your project seriously. +The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see TechDocs [Assistance program](./TechDoc-Assistance-Program.md). diff --git a/TechDoc-Assistance-Program.md b/TechDoc-Assistance-Program.md index 04754ee..802be15 100644 --- a/TechDoc-Assistance-Program.md +++ b/TechDoc-Assistance-Program.md @@ -1,8 +1,8 @@ -# Technical Documentation Assistance Program +# 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](analysis/analysis-tools/criteria.md. (Often, documentation help is requested when a project requests promotion to a new maturity level.) +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. 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. @@ -15,41 +15,42 @@ Some level of familiarity with the technical documentation process is required t - Work effectively with technical writers - Draft technical documentation (for non-writers) -- Improve the chances of a good outcome from the Tech Doc Assistance Program +- 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 Technical Documentation Assistance Program, project contributors should do the training *before* engaging a documentation specialist to complete the documentation analysis. +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 +## Phase 1: Documentation analysis -A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed by the CNCF Tech Docs program, the writer: +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, based on a number of criteria in three categories, using a rubric developed by CNCF. The categories are: +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. 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 proposed maturity level. -1. Writes an implementation plan describing improvements that address the gaps identified in the analysis. +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 +## 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, not days, to complete. +- 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 +## 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 +## Phase 4: Impact analysis -Measurement is vital to any process improvement effort, and this is currently the weakest point of the TechDoc Assistance Program. We do no offer any tools to measure the impact of doc improvements, although we can assure you that they are profound. Projects are encouraged to collect metrics on documentation effectiveness. +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.