Skip to content

Latest commit

 

History

History
107 lines (87 loc) · 5.49 KB

assistance.md

File metadata and controls

107 lines (87 loc) · 5.49 KB
Raw

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. Often, projects request an analysis in support of promotion to a new maturity level.
  2. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project.
  3. Expand on the recommended changes in an implementation plan.
  4. Break down the implementation into a documentation project backlog comprising a GitHub Issues list.
  5. Support the project team's contributors in taking up and completing the issue backlog items.
  6. 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.

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)
  2. 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.
    2. 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).
    3. Website: The technical infrastructure behind the documentation and the project's web presence, including website generation, versioning, SEO, analytics, and security.
  2. Collaborates with project leadership to identify user roles and objectives for software users.
  3. Proposes changes, if necessary, to the organization and content of the documentation to close gaps with the target maturity level.
  4. 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.