Merge branch 'main' into specificationpage

Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com>

.prettierignore

@@ -1 +1 @@
-# Nothing to ignore at the moment.
+/docs/localization/ja

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

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/)

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

analyses/0012-TUF/analysis.md

@@ -335,7 +335,7 @@ Scale:
   to work on.
 - Information about the TUF **slack channel** is available on the website in
 - Information about the TUF **slack channel** is available on the website in
-- Information about the TUF **slack channel** is available on the website in
+
   areas of interest
 
 #### Communication methods documented
@@ -345,9 +345,7 @@ Scale:
   visible on the website repo README for easy access. visible on the website
   repo README for easy access.
 
-  no information about project meetings. Instead, the users are directed to join
-  no information about project meetings. Instead, the users are directed to join
-  the
+  no information about project meetings. Instead, the users are directed to join the
   [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file)
 
 - Information about the mailing list is included in the documentation. There's
@@ -404,8 +402,6 @@ Scale:
 - Maintain issues, track,close and stale old issues to reduce backlog.
 - Include instructions on how to contribute to a CONTRIBUTING guideline, e.g.,
   how interest.
-- Include instructions on how to contribute to a CONTRIBUTING guideline, e.g.,
-  how interest.
 
 #### New contributor getting started content
 
@@ -446,8 +442,6 @@ Scale:
 
 4 = Meets or exceeds standards
 
-- There's no guideline or tutorial to assist users in generating the website
-  from 5 = Exemplary
 - There's no guideline or tutorial to assist users in generating the website
   from 5 = Exemplary
 
@@ -456,9 +450,6 @@ Scale:
 navigation option is a menu bar. This makes it difficult to find information.
 the website repo.
 
-navigation option is a menu bar. This makes it difficult to find information.
-the website repo.
-
 - Information about the website build, tools and how to generate it are not
   available on the website or the docs repo.
 - Intra-site search mechanism is not available from the website. The only
@@ -481,7 +472,6 @@ The website docs analysis is in progress.
 - The website follows a mobile-first design with all pages, menu's and features
   visible on smaller screens.
 - There's a recognizable brand for the project, a logo, and a blue-white color
-- There's a recognizable brand for the project, a logo, and a blue-white color
 - The website does not provide a text-to-speech option for users.
 
 #### Branding and design

analyses/0012-TUF/implementation.md

@@ -66,13 +66,6 @@ structure:
 - **Home page**
 - **Documentation**: Overview of TUF
 
-  - Getting started: Adopters, contributors, Timeline, and History
-  - Project
-  - Metadata
-  - Enhancement proposals
-  - Adoptions
-  - Implementations
-  - Security audits
   - FAQ
 
 - **Community**: You can have two sections.
@@ -182,7 +175,6 @@ notifications about meetings. I like how the
 
 ## Proposed Information Architecture for the TUF Website
 
-The table below outlines the current information architecture (IA) of the
 [TUF website](https://theupdateframework.io/) and the proposed IA for the new
 website.
 
@@ -218,8 +210,7 @@ website.
 |                          |                 | - Getting started        |
 |                          |                 | - Adoptions              |
 |                          |                 | - FAQ                    |
-|                          | Specs           | -Specification (latest)  |
-|                          |                 | - Specification index  |
+
 |                          | Community       | - Code of conduct        |
 |                          |                 | - Learn and connect      |
 |                          |                 | - Develop and contribute |

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>
 

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

docs/localization/README.md

@@ -11,3 +11,7 @@ Every guide here must meet the following requirements:
 - Meets the requirements of the original open-source license.
 
 Guides here must not violate copyright or licensing requirements.
+
+## Localizations
+
+- [Japanese](ja/README.md)