diff --git a/README.md b/README.md index b19c2bf..be0b70e 100644 --- a/README.md +++ b/README.md @@ -3,35 +3,24 @@ 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 TechDocs team. +- `docs` contains collected resources for building websites and developing + documentation, including recommended tools and practices, how-tos, and + evaluation checklists. Included are specific guidelines for: + - Setting up and maintaining a documentation website. + - Writing technical documentation for a project. + - Getting assistance from the CNCF TechDocs community. + - Analyzing project documentation, for use by CNCF TechDocs staff (in + `docs/analysis`). +- `analyses` (not to be confused with `docs/analysis`) contains all the + completed documentation analyses. -## CNCF TechDocs team - -The full-time staff of the CNCF Tech Docs team is: - - - -| GitHub ID | Role | -| -------------------------------------------------- | ------------------------------------- | -| [@chalin](https://github.com/chalin) | Senior technical writer | -| [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer | -| [@thisisobate](https://github.com/thisisobate) | Developer advocate | - - - - -Various consultants and volunteers also contribute to CNCF Tech Docs projects. +## TechDocs Q&A -## Office hours +The CNCF tech docs team holds a Zoom call to answer questions and discuss +anything to do with documentation. Calls are held on the [fourth Wednesday of +every month at 8am Pacific time][date-time]. -The CNCF tech docs team holds office hours on the [fourth Wednesday of every -month at 8am Pacific time][date-time]. - -Office hours started on 30 September 2020. +TechDocs Q&A (formerly called _Office Hours_) started on 30 September 2020. ### Meeting link @@ -44,15 +33,26 @@ We store ongoing meeting notes in a ## Assistance program for technical documentation -The TechDocs team can assist CNCF projects analyze and improve their +The TechDocs team can help CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance program](docs/assistance.md). -### Resources +## CNCF TechDocs team + +The full-time staff of the CNCF Tech Docs team is: + + + +| GitHub ID | Role | +| -------------------------------------------------- | ------------------------------------- | +| [@chalin](https://github.com/chalin) | Senior technical writer | +| [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer | +| [@thisisobate](https://github.com/thisisobate) | Developer advocate | + + + -The `docs/` directory contains collected resources for building websites and -developing documentation, including recommended tools and practices, how-tos, -and evaluation checklists. +Various consultants and volunteers also contribute to CNCF Tech Docs projects. [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index 7508886..a759b48 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -137,7 +137,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... - - [FAQ](https://keda.sh/docs/2.13/faq/) + - [FAQ](https://keda.sh/docs/2.13/reference/faq/) - Glossary - [Scalers](https://keda.sh/docs/2.13/scalers/) - [ActiveMQ](https://keda.sh/docs/2.13/scalers/activemq/) diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index 2d3bb63..c46e690 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -180,7 +180,7 @@ or provide a starting point. - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... - - [FAQ](https://keda.sh/docs/2.13/faq/) + - [FAQ](https://keda.sh/docs/2.13/reference/faq/) - Glossary # Separate reference and task information diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index c0c9e61..e6719fb 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -21,7 +21,7 @@ documentation. We evaluate on the following: - If the product exposes an API, is there a complete reference? - Is content up to date and accurate? -Examples: +Example: - @@ -39,7 +39,10 @@ specifically for them. We evaluate on the following: top of your information architecture? - Is there easily copy-pastable sample code or other example content? -Examples: + + + +Example: - @@ -55,7 +58,7 @@ We evaluate on the following: directory structure? Is a localization framework present? - Do you have a clearly documented method for versioning your content? -Examples: +Example: - @@ -105,7 +108,7 @@ We evaluate on the following: join those meetings? - Are mailing lists documented? -Examples: +Example: - @@ -119,7 +122,7 @@ We evaluate on the following: - Are issues well-documented (i.e., more than just a title)? - Are issues maintained for staleness? -Examples: +Example: - (all of open tracing’s backlogs are well maintained!) @@ -136,7 +139,7 @@ We evaluate on the following: - Is there a document specifically for new contributors/your first contribution? - Do new users know where to get help? -Examples: +Example: - @@ -148,9 +151,9 @@ We evaluate on the following: - Is project governance clearly documented? -Examples: +Example: -- Any graduated CNCF project +- ## Website @@ -181,16 +184,20 @@ maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. - **Sandbox** - - [Website guidelines](../website-guidelines-checklist.md): majority of the + - [Website guidelines](../website-guidelines-checklist.md): a majority of the guidelines are satisfied - - [Docs assessment][]: consider [submitting a request][service desk] for an assessment - as early as possible to avoid documentation and website rework. - **Project documentation** may or may not be present -- it is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website - - _Example_: website with a single homepage, without any documentation or, as - was mentioned above, linking out to an external (preexisting) source for - docs + - _Example_: website with a single homepage, without any documentation or, + as was mentioned above, linking out to an external (preexisting) source + for docs + - _However_: consider reading the recommended practices in this repository + and implementing as many of the best practices as you can. This groundwork + will pay big dividends later when you need to upgrade your practices and + update your documentation as an incubating project. Assistance is + available from CNCF TechDocs anytime, including answers to individual + questions or a documentation workshop. - **Incubating** - [Website guidelines][]: all guidelines are satisfied. - [Docs assessment][]: request an (re-)assessment through the CNCF [service @@ -207,7 +214,7 @@ requirements for sandbox projects. - The website repo is in an [archived state][] - The archived status of the project must be obvious to those visiting the website, such as through the use of a prominent banner. - - If a successor project exists, link to it's website and/or migration + - If a successor project exists, link to its website and/or migration documentation. [archived state]: @@ -254,9 +261,9 @@ We evaluate on the following: - Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? - Is the brand used across the website consistently? -- Is the website’s typography clean and well-suited for reading? +- Is the website’s typography clean and legible? -Examples: +Example: - @@ -282,9 +289,10 @@ Examples: ### SEO, Analytics and site-local search -SEO helps users find your project and it's documentation, and analytics helps -you monitor site traffic and diagnose issues like page 404s. Intra-site search, -while optional, can offer your readers a site-focused search results. +SEO helps users find your project and its documentation, and analytics helps you +monitor site traffic and diagnose issues like page 404s. Intra-site search, +while optional, offers your readers site-focused search results and is strongly +recommended. We evaluate on the following: @@ -313,7 +321,7 @@ We evaluate on the following: - Are site build times reasonable? - Do site maintainers have adequate permissions? -Examples: +Example: - diff --git a/docs/assistance.md b/docs/assistance.md index a322e87..5362657 100644 --- a/docs/assistance.md +++ b/docs/assistance.md @@ -1,9 +1,9 @@ # 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: +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 @@ -18,6 +18,13 @@ process is designed to: 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