Criteria: sandbox update/clarification (cncf#266)

* Update README.md Corrected with new directory structure. Reorganized description. Signed-off-by: Dave Welsch <[email protected]> * Update criteria.md Updated sandbox website assessment requirement. Miscellaneous small corrections. Signed-off-by: Dave Welsch <[email protected]> * Update README.md Fix formatting errors, primarily line legth/LINT. Signed-off-by: Dave Welsch <[email protected]> * Update criteria.md Fix MD linter and line-length errors. Signed-off-by: Dave Welsch <[email protected]> * Update README.md Trailing spaces? Really? Signed-off-by: Dave Welsch <[email protected]> * Update criteria.md Signed-off-by: Dave Welsch <[email protected]> * Update keda-implementation.md Fixed faq link Signed-off-by: Dave Welsch <[email protected]> * Update keda-issues.md Signed-off-by: Dave Welsch <[email protected]> * fixing formatting issues brought up by prettier Signed-off-by: Nate W <[email protected]> * Update docs/analysis/criteria.md Co-authored-by: Dave Welsch <[email protected]> Signed-off-by: Nate W <[email protected]> * Update assistance.md Added a note to address program differences for projects at the Sandbox maturity level. Signed-off-by: Dave Welsch <[email protected]> * Update assistance.md Signed-off-by: Dave Welsch <[email protected]> --------- Signed-off-by: Dave Welsch <[email protected]> Signed-off-by: Nate W <[email protected]> Co-authored-by: Nate W <[email protected]>
dwelsch-esi · Jul 30, 2024 · 3959be8 · 3959be8
1 parent d144317
commit 3959be8
Show file tree

Hide file tree

Showing 5 changed files with 72 additions and 57 deletions.
diff --git 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:
-
-<!-- markdownlint-disable line-length -->
-
-| 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                    |
-
-<!-- markdownlint-enable line-length -->
-<!-- cSpell:ignore chalin nate thisisobate -->
-
-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:
+
+<!-- markdownlint-disable line-length -->
+
+| 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                    |
+
+<!-- markdownlint-enable line-length -->
+<!-- cSpell:ignore chalin nate thisisobate -->
 
-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
@@ -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/latest/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
@@ -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/latest/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
@@ -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:
 
 - <https://prometheus.io/docs>
 
@@ -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:
+<!-- markdownlint-enable line-length -->
+<!-- cSpell:ignore OSes copy-pastable Algolia Docsy -->
+
+Example:
 
 - <https://falco.org/docs/getting-started/>
 
@@ -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:
 
 - <https://kubernetes.io/docs/>
 
@@ -105,7 +108,7 @@ We evaluate on the following:
   join those meetings?
 - Are mailing lists documented?
 
-Examples:
+Example:
 
 - <https://prometheus.io/community/>
 
@@ -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:
 
 - <https://github.com/opentracing/opentracing.io/issues> (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:
 
 - <https://github.com/helm/community>
 
@@ -148,9 +151,9 @@ We evaluate on the following:
 
 - Is project governance clearly documented?
 
-Examples:
+Example:
 
-- Any graduated CNCF project
+- <https://github.com/envoyproxy/envoy/blob/main/GOVERNANCE.md>
 
 ## 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:
 
 - <https://helm.sh/>
 
@@ -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:
 
 - <https://kubernetes.io>
 

diff --git 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