Move assessments to analyses and more

Signed-off-by: Patrice Chalin <pchalin@gmail.com>

.markdown-link-check.json

@@ -2,6 +2,9 @@
   "ignorePatterns": [
     {
       "pattern": "^http://localhost"
+    },
+    {
+      "pattern": "^#"
     }
   ],
   "timeout": "3s",

README.md

@@ -35,9 +35,7 @@ We store ongoing meeting notes in a [Google doc](https://docs.google.com/documen
 
 ## Assistance program for technical documentation
 
-The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][].
-
-[assistance-program]: ./assistance.md
+The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance program](docs/assistance.md).
 
 ### Resources
 

docs/analytics.md

@@ -135,8 +135,6 @@ Follow these steps:
     -- provided that there are active users. You should see roughly the same
     number and distribution of active users reported by the UA console.
 
-<a name="stage-2"></a>
-
 ### Stage 2 - configure the GA4 ID as the main analytics ID
 
 GA4 only works when your project's website is configured using the [gtag.js][]
@@ -198,6 +196,6 @@ that your project is using.
 [issue #108]: https://github.com/cncf/techdocs/issues/108
 [migration-help]: https://support.google.com/analytics/answer/10759417
 [opentelemetry.io/layouts/partials/google-analytics.html]: https://github.com/open-telemetry/opentelemetry.io/blob/3d8a59ea508b46497500297f334a079a4f91e293/layouts/partials/google-analytics.html
-[stage 2]: #stage-2
+[stage 2]: #stage-2---configure-the-ga4-id-as-the-main-analytics-id
 [status table]: https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA
 [ua]: https://support.google.com/analytics/answer/11583528

assistance.md → docs/assistance.md

@@ -2,7 +2,7 @@
 
 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:
 
-1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](docs/analysis/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level.
+1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](analysis/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level.
 1. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project.
 1. Expand on the recommended changes in an implementation plan.
 1. Break down the implementation into a documentation project backlog comprising a GitHub Issues list.

docs/searching-documentation.md

@@ -1,43 +1,45 @@
 # Documentation Search
 This page describes some common alternatives for static site search.
 
-* [Lunr](#lunr)
 * [Google search](#programmable-search-engine-by-google)
 * [Docsearch by Algolia](#docsearch-by-algolia)
-
-# Docsearch by Algolia
-[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the Algolia search engine that crawls your docs and provides a dropdown search experience on your website.
-
-## Pros
-- Provides Front-end widgets out of the box: search input, dynamic positioning of search results, etc.
-- Integrations with popular frameworks
-- Support for multi-language search.
-
-## Cons
-- Not entirely free- Limited to 10k records
-- Limited access to features.
+* [Lunr](#lunr)
 
 
-# Programmable Search Engine by Google
+## Programmable Search Engine by Google
 [Google’s programmable search engine](https://developers.google.com/custom-search/docs/overview) is a search tool that crawls your **live site** and renders results on your website.
 
 
-## Pros
+### Pros
 - Easy to configure and setup
 - Multi-language support
 - Support for image search
 - Search across a specified collection of sites or pages
 - No daily limits for queries or records.
 
 
-## Cons
+### Cons
 - Search index is completely managed and hosted on Google servers.
 
-# Lunr
+
+## Docsearch by Algolia
+[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the Algolia search engine that crawls your docs and provides a dropdown search experience on your website.
+
+### Pros
+- Provides Front-end widgets out of the box: search input, dynamic positioning of search results, etc.
+- Integrations with popular frameworks
+- Support for multi-language search.
+
+### Cons
+- Not entirely free- Limited to 10k records
+- Limited access to features.
+
+
+## Lunr
 [Lunr.js](https://lunrjs.com/) is a small, full-text search library for use in the browser. Lunr enables you to provide a great search experience without needing external, server-side, search services.
 
 
-## Pros
+### Pros
 - Support for offline search
 - No external package dependency
 - Completely free and open source
@@ -46,11 +48,11 @@ This page describes some common alternatives for static site search.
 - Search index is completely managed and hosted by the owner.
 
 
-## Cons
+### Cons
 - Can be complex to configure and setup (If a team is already using hugo/docsy, this should be *very* easy to setup).
 - Depending on site setup, may require javascript knowledge
 
-# When Is It Best To Use One Over Another?
-If you are looking to create a search capability for your open source project without having to depend on a 3rd party service, then you should consider using [Lunr](https://lunrjs.com/). You can take a look at [this custom implementation](https://github.com/vitessio/website/pull/1119) or [Hugo/Docsy implementation](https://github.com/etcd-io/website/pull/403) to see the different ways we used Lunr to implement search.  
+## When Is It Best To Use One Over Another?
+If you are looking to create a search capability for your open source project without having to depend on a 3rd party service, then you should consider using [Lunr](https://lunrjs.com/). You can take a look at [this custom implementation](https://github.com/vitessio/website/pull/1119) or [Hugo/Docsy implementation](https://github.com/etcd-io/website/pull/403) to see the different ways we used Lunr to implement search.
 
 If you are looking to create a search engine that not only focuses on the contents of one website (site search), but on a particular topic from multiple sites, then you should consider the [Programmable Search Engine (Google search)](https://developers.google.com/custom-search/docs/overview).

docs/versioning-documentation.md

@@ -120,7 +120,7 @@ The subdomain scheme uses some simpler template code to generate links, only hav
 Each version of the documentation is its own site
 - Uses git feature branches rather than folders to organize versions
 - Separate site in Netlify for each version supported
-- Simpler template code, more complex config 
+- Simpler template code, more complex config
 
 Scores high on:
 - Localization / Internationalization
@@ -146,7 +146,7 @@ Pursley et al. (2020, L4-L9)<sup>[4](#footnote4)</sup>
 
 The dropdown example is made simpler because the config is more complex and because the server setup is more complex.
 
-https://kubernetes.io `website/config.toml` 
+https://kubernetes.io `website/config.toml`
 ```toml
 [[params.versions]]
 fullversion = "v1.20.0"
@@ -184,14 +184,14 @@ For small to medium sized sites using one language/location, a folder based meth
 
 <a name="footnote1">1</a>: [Bannister, T.](https://github.com/sftim) et al. (2020, December 23). kubernetes/website. GitHub. Retrieved February 2, 2021 from [https://github.com/kubernetes/website/blob/ 7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml](https://github.com/kubernetes/website/blob/7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml)
 
-<a name="footnote2">2</a>: [Batard, T.](https://github.com/tbatard) (2020, August 13). _vmware-tanzu/velero_. GitHub. Retrieved January 19, 2021 from [https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html](https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html) 
+<a name="footnote2">2</a>: [Batard, T.](https://github.com/tbatard) (2020, August 13). _vmware-tanzu/velero_. GitHub. Retrieved January 19, 2021 from [https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html](https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html)
 
 
- <a name="footnote3">3</a>: [Brubaker, N.](https://github.com/nrb), [Rosland, J.](https://github.com/jonasrosland), [Thompson, C.](https://github.com/carlisia), [Batard, T.](https://github.com/tbatard) (2020, September 16). _vmware-tanzu/velero_. GitHub. Retrieved February 2, 2021 from [https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml](https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml) 
+ <a name="footnote3">3</a>: [Brubaker, N.](https://github.com/nrb), [Rosland, J.](https://github.com/jonasrosland), [Thompson, C.](https://github.com/carlisia), [Batard, T.](https://github.com/tbatard) (2020, September 16). _vmware-tanzu/velero_. GitHub. Retrieved February 2, 2021 from [https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml](https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml)
 
- <a name="footnote4">4</a>: [Pursley, B.](https://github.com/brianpursley), [Horgan, C.](https://github.com/celestehorgan), [Takahashi, S.](https://github.com/shuuj3) (2020, July 21). _kubernetes/website_. GitHub.  Retrieved February 2, 2021 from [https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html](https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html) 
+ <a name="footnote4">4</a>: [Pursley, B.](https://github.com/brianpursley), [Horgan, C.](https://github.com/celestehorgan), Takahashi, S. (2020, July 21). _kubernetes/website_. GitHub.  Retrieved February 2, 2021 from [https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html](https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html)
 
 ---
 
-This page has been adapted from the [Technical Documentation Versioning slide show](https://technical-documentation-versioning.netlify.app/), its source can be found here: [https://github.com/nate-double-u/technical-documentation-versioning](https://github.com/nate-double-u/technical-documentation-versioning). 
+This page has been adapted from the [Technical Documentation Versioning slide show](https://technical-documentation-versioning.netlify.app/), its source can be found here: [https://github.com/nate-double-u/technical-documentation-versioning](https://github.com/nate-double-u/technical-documentation-versioning).
 

package.json

@@ -8,7 +8,7 @@
     "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'",
     "_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'",
     "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
-    "check:links": "npx markdown-link-check --config .markdown-link-check.json *.md",
+    "check:links": "bash -c 'for f in *.md docs/*.md; do npx markdown-link-check --config .markdown-link-check.json $f || exit 1; done'",
     "check:spelling": "npx cspell --no-progress -c .cspell.yml .",
     "check": "npm run seq -- $(npm run -s _list:check:*)",
     "fix:format": "npm run _check:format -- --write",