mirror of https://github.com/cncf/techdocs.git
108 lines
5.5 KiB
Markdown
108 lines
5.5 KiB
Markdown
# 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
|
|
TechDocs 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/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.
|
|
|
|
**Note**: The Program focuses on established projects at the _incubating_ and
|
|
_graduated_ maturity levels. The Program offers help for _sandbox_ projects as
|
|
well, but with less emphasis on analyzing existing documentation and more on
|
|
establishing good practices and starting a minimally viable documentation set.
|
|
For more information contact the
|
|
[CNCF TechDocs team](https://servicedesk.cncf.io/).
|
|
|
|
## 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.
|