[CI & docs] Rework of analysis docs + improved checks

Signed-off-by: Patrice Chalin <[email protected]>

.github/workflows/format-check.yml

@@ -14,5 +14,16 @@ jobs:
           node-version-file: .nvmrc
           cache: npm
           cache-dependency-path: package.json
-      - name: Check file format
-        run: npm run check:format
+      - run: npm run check:format
+
+  markdown-linter:
+    name: MARKDOWN linter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: package.json
+      - run: npm run check:markdown

.markdownlint.yaml

@@ -0,0 +1,5 @@
+# See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+# and https://github.com/DavidAnson/markdownlint/blob/main/README.md
+
+list-marker-space: false
+no-inline-html: false

README.md

@@ -13,27 +13,29 @@ team. The repo contains the following directories:
 
 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.
 
 ## Office hours
 
-The CNCF tech docs team holds office hours on the
-[fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours).
+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.
 
 ### Meeting link
 
-Zoom link:
-https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e
+- [Zoom meeting 95471930872]
 
 ### Meeting notes
 
@@ -51,3 +53,8 @@ documentation. For details, see the TechDocs
 The `docs/` directory contains collected resources for building websites and
 developing documentation, including recommended tools and practices, how-tos,
 and evaluation checklists.
+
+[date-time]:
+  https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours
+[Zoom meeting 95471930872]:
+  https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e

analyses/README.md

@@ -15,7 +15,7 @@ The goals of a CNCF technical documentation analysis are to:
   investment. These improvements are documented as _recommendations_ in the
   analysis document and expanded in a companion
   [implementation plan](../docs/analysis/templates/implementation.md) and
-  [issues backlog](../docs/analysis/templates/umbrella-issue.md).
+  [issues backlog](../docs/analysis/templates/issues-list.md).
 
 ## Audience
 

docs/analysis/README.md

@@ -1,11 +1,7 @@
 # TechDoc Analysis
 
-## Contents
+This section contains instructions and criteria for completing a documentation
+analysis, including a [how-to](./howto.md) guide and analysis
+[criteria](./criteria.md)
 
-This directory contains instructions and criteria for completing a documentation
-analysis, including a [how-to][] guide and analysis [criteria][].
-
-Templates for the analyses are in the resources directory.
-
-[how-to]: ./howto.md
-[criteria]: ./criteria.md
+For templates, see [templates](./templates/).

docs/analysis/criteria.md

@@ -23,7 +23,7 @@ documentation. We evaluate on the following:
 
 Examples:
 
-- https://prometheus.io/docs/
+- <https://prometheus.io/docs>
 
 ### New user content
 
@@ -41,7 +41,7 @@ specifically for them. We evaluate on the following:
 
 Examples:
 
-- https://falco.org/docs/getting-started/
+- <https://falco.org/docs/getting-started/>
 
 ### Content maintainability & site mechanics
 
@@ -57,7 +57,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://kubernetes.io/docs/
+- <https://kubernetes.io/docs/>
 
 ### Content creation processes
 
@@ -74,9 +74,9 @@ We evaluate on the following:
 
 Examples:
 
-- https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly
+- <https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md> (clearly
   documented maintainers)
-- https://thanos.io/tip/contributing/how-to-contribute-to-docs.md
+- <https://thanos.io/tip/contributing/how-to-contribute-to-docs.md>
 
 ### Inclusive language
 
@@ -107,7 +107,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://prometheus.io/community/
+- <https://prometheus.io/community/>
 
 ### Beginner friendly issue backlog
 
@@ -121,7 +121,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://github.com/opentracing/opentracing.io/issues (all of open tracing’s
+- <https://github.com/opentracing/opentracing.io/issues> (all of open tracing’s
   backlogs are well maintained!)
 
 ### New contributor getting started content
@@ -138,7 +138,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://github.com/helm/community
+- <https://github.com/helm/community>
 
 ### Project governance documentation
 
@@ -165,7 +165,8 @@ problems, keeping source files in two places:
 - makes it more complicated to generate the documentation from source files
 
 Ideally, all website files should be in the **website repo** itself.
-Alternatively, files should be brought into the website repo via [git submodules][].
+Alternatively, files should be brought into the website repo via
+[git submodules](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules).
 
 If a project chooses to keep source files in multiple repos, they need a clearly
 documented strategy for managing mirrored files and new contributions.
@@ -257,7 +258,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://helm.sh/
+- <https://helm.sh/>
 
 ### Case studies/social proof
 
@@ -275,9 +276,9 @@ We evaluate on the following:
 
 Examples:
 
-- https://www.fluentd.org/testimonials (user testimonials)
-- https://goharbor.io/ (logo wall)
-- https://blog.rook.io/ (blog)
+- <https://www.fluentd.org/testimonials> (user testimonials)
+- <https://goharbor.io/> (logo wall)
+- <https://blog.rook.io/> (blog)
 
 ### SEO, Analytics and site-local search
 
@@ -314,7 +315,7 @@ We evaluate on the following:
 
 Examples:
 
-- http://kubernetes.io
+- <https://kubernetes.io>
 
 ### Other
 

docs/analysis/howto.md

@@ -2,75 +2,78 @@
 
 ## Audience
 
-This document is for members of the CNCF TechDocs team, including contractors or
-consultants, who need to conduct or assist with an analysis of a CNCF
-open-source project's technical documentation.
+This document is for members of the CNCF TechDocs team and others who wish to
+conduct or assist with an analysis of a CNCF open-source project's technical
+documentation.
 
 ## Purpose
 
 The goals of a CNCF technical documentation analysis are to:
 
 - Examine the current project technical documentation and website against the
-  CNCF's analysis framework, as described in the doc analysis
-  [criteria](./criteria.md).
-- Compare the documentation against the current or proposed maturity level for
-  the overall project.
-- Recommends a program of key improvements with the largest return on
-  investment. These improvements are documented as _recommendations_ in the
-  analysis document and expanded in a companion
+  CNCF's analysis [criteria].
+- Compare the documentation against the current or proposed [project
+  maturity level].
+- Recommend a program of key documentation improvements with the largest return
+  on investment. These improvements are documented as _recommendations_ in the
+  analysis document, and expanded in a companion
   [implementation plan](./templates/implementation.md) and
-  [issues backlog](./templates/umbrella-issue.md).
+  [issues list](./templates/issues-list.md).
 
 ## Doing a Tech Docs Analysis
 
-The tech docs analysis consists of some repository bookkeeping (Prerequisites),
+The tech docs analysis consists of some repository bookkeeping (prerequisites),
 then of three overall tasks:
 
-1. Write the analysis document: Evaluate the existing project documentation with
-   respect to the project maturity level (or proposed maturity level, if the
-   analysis is associated with an upgrade request). Identify gaps with CNCF
-   criteria. Write general recommendations to close the largest and most
-   important gaps.
-2. Write the implementation plan: Decompose the recommendations to specific
+1. Write the analysis document: evaluate the existing project documentation with
+   respect to the [project maturity level] or proposed maturity level, if the
+   analysis is associated with a project upgrade request. Identify gaps with
+   CNCF [criteria]. Write general recommendations to close the largest and most
+   important identified issues.
+2. Write a implementation plan: decompose recommendations in to specific
    improvement suggestions. These can be additions or revisions to the docs;
    reorganization; website infrastructure changes; or any other work that will
-   close the gaps. Make suggestions specific (if you propose reorganizing a
-   section, for example, provide an outline) but provide enough information that
-   a contributor could solve the problem differently if they have a different
-   idea (make it clear that your proposed outline is only one possible
-   reorganization, e.g.).
-3. Write the issue backlog.
+   close address issues. Make suggestions specific enough (for example, if you
+   propose reorganizing a section then provide an outline) without being overly
+   constraining so that a contributor could solve the problem differently if
+   they have a different solution. For example, make it clear that your proposed
+   outline is only one possible reorganization.
+3. Write an issue backlog.
 
-Finally, there are follow-up steps including creating GitHub issues and a pull
-request, and getting approval from project maintainers.
+Finally, there are follow-up steps including:
+
+- Creating GitHub issues and a pull request
+- Getting approval from project maintainers
 
 ### Prerequisites
 
-This process assumes you have some familiarity with GitHub repositories and pull
-requests (PRs).
+This section assumes you are familiar with GitHub repositories and pull requests
+(PRs). If you need a refresher, see
+[Get started](https://docs.github.com/en/get-started) from the GitHub docs.
+
+Project analyses are kept in the
+[CNCF tech docs repository](https://github.com/cncf/techdocs). Clone and prepare
+for
 
 1. Clone the [CNCF tech docs repository](https://github.com/cncf/techdocs).
-1. Create a branch for the analysis.
-1. In the new branch, create a directory for the analysis in the CNCF tech docs
-   /analysis directory. Name the directory `00NN-_PROJECT_`, where _NN_ is the
+2. Create a branch for the analysis.
+3. In the new branch, create a directory for the analysis in the CNCF tech docs
+   [analyses] directory. Name the directory `00NN-_PROJECT_`, where _NN_ is the
    next index available in the directory (check for PRs as well, if someone else
    is working on tech doc analyses), and where _PROJECT_ is a short but not
    abbreviated project name. For example, for Kubernetes _PROJECT_ would be
    _kubernetes_, not _k8s_.
-1. Copy and rename the analysis doc templates from the
-   `/analysis/analysis-tools` directory as follows: `analysis-template.md` >
-   `_PROJECT_-analysis.md`; `implementation-template.md` >
-   `_PROJECT_-implementation.md`; and `umbrella-issue-template.md` >
-   `_PROJECT_-issues.md`.
+4. Copy all the doc analysis [templates].
 
 ### Writing the Analysis document
 
-Edit `_PROJECT_-analysis.md` and follow these steps to complete the first step,
-the analysis:
+Follow the steps outlined below as a part of writing the project's analysis
+document. Record your findings in the project's
+[analysis.md](./templates/analysis.md) file.
 
-1. Define the scope of the analysis. Edit "Scope of analysis" to reflect URLs
-   and repositories included and excluded from the analysis.
-1. Review the in-scope URLs and repositories for compliance with the rubric
+1. Define the **scope** of the analysis. Edit "Scope of analysis" to reflect
+   URLs and repositories included and excluded from the analysis.
+2. Review the in-scope URLs and repositories for compliance with the rubric
    criteria. Note any gaps, as well as any areas that exceed criteria or are
    exceptionally well executed. I find it easiest to do this separately for each
    of the three areas of concern (project doc, contributor doc, website), making
@@ -81,11 +84,11 @@ the analysis:
    level (or proposed maturity level, if the analysis is part of a petition for
    upgrade). Write comments to note the most important gaps and best-executed
    features of the documentation.
-1. Assign ratings to each criterion based on your comments and compliance with
+3. Assign ratings to each criterion based on your comments and compliance with
    the maturity level expectations in the rubric. The ratings are
    self-explanatory. Keep in mind that "needs improvement" or "meets standards"
    is with respect to the current (or proposed) maturity level.
-1. Write recommendations. The template implies that you'll do this for every
+4. Write recommendations. The template implies that you'll do this for every
    criterion; the "Recommendations" headings mirror the "Comments" headings.
    However, if some alternative framework makes more sense, use that. For
    example, it might be that two or three of the product documentation criteria
@@ -205,7 +208,14 @@ interested parties to get feedback on the analysis and implementation plan.
 
 ### Creating GitHub issues
 
-Enter the backlog issues from the issues document into the project documentation
-GitHub repository using the format in the umbrella-issues-template.md and
-issues-template.md files. Create one GitHub issue per backlog issue, and create
-an umbrella issue that contains a checklist item for each issue.
+Create issues in the project documentation GitHub repository for:
+
+- Each issues in the [issues list].
+- An umbrella issue that provides a context for the previously created
+  individual issues.
+
+[analyses]: ../../analyses/
+[criteria]: ./criteria.md
+[project maturity level]: https://www.cncf.io/project-metrics
+[templates]: ./templates/
+[issues list]: ./templates/issues-list.md

docs/analysis/templates/README.md

@@ -1,6 +1,6 @@
 # TechDoc Analysis Templates
 
-This directory contains templates for analyzing a CNCF project's documentation.
+This section contains templates for analyzing a CNCF project's documentation.
 
 Use the templates in this directory to perform a documentation analysis for
 CNCF. These materials provide:
@@ -12,6 +12,5 @@ CNCF. These materials provide:
 - Emphasis on effective documentation that serves all users associated with the
   project.
 
-Resources for completing a documentation analysis, including a
-[how-to](../howto.md) guide and analysis [criteria](../criteria.md), are in the
-`docs` directory.
+For guidance in completing a documentation analysis, see
+[Analysis how-to](../howto.md) and [criteria](../criteria.md) pages.