From a69646129aa4ff3100d771157e9dbcf82f02fa7c Mon Sep 17 00:00:00 2001 From: Nate W Date: Wed, 12 Mar 2025 09:42:44 -0700 Subject: [PATCH 001/104] updating domain and netlify information (#299) * updating domain and netlify information Signed-off-by: Nate W * Update docs/services.md Co-authored-by: Patrice Chalin Signed-off-by: Nate W --------- Signed-off-by: Nate W Co-authored-by: Patrice Chalin Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 + docs/netlify-domains-setup.md | 25 +++++++++++++------------ docs/services.md | 6 +++++- 3 files changed, 19 insertions(+), 13 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 633b55d..8dda349 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -27,6 +27,7 @@ words: - Docsy - keda - kedacore + - nate - subpages - techdocs - toolkits diff --git a/docs/netlify-domains-setup.md b/docs/netlify-domains-setup.md index 79db247..94351d4 100644 --- a/docs/netlify-domains-setup.md +++ b/docs/netlify-domains-setup.md @@ -7,16 +7,16 @@ cSpell:ignore: caniszczyk ## Netlify If a project already has its own Netlify instance, ask them to add -[@caniszczyk][] as administrator. As a part of project onboarding, any billing -information should be taken care of. If it isn't, ask them to open a -[CNCF Service Desk](https://github.com/cncf/servicedesk) ticket. +[@caniszczyk][] and [@nate-double-u][] as administrators. As a part of project +onboarding, any billing information should be taken care of. If it isn't, ask +them to open a [CNCF service desk][] ticket. If a project does not have a website, or is migrating from using GitHub pages to Netlify, create a new site for them under the CNCF Projects netlify instance. ### Netlify maintainers -- Ensure that [@caniszczyk][] is an Owner. +- Ensure that [@caniszczyk][] and [@nate-double-u][] are owners. - Contact the project and ask for **at least two** maintainers for Netlify. You will need their GitHub usernames. Add them either as Collaborators to specific sites (if in the CNCF Projects Netlify team) or as Collaborators for the @@ -25,17 +25,16 @@ Netlify, create a new site for them under the CNCF Projects netlify instance. ## Domains If a project has a pre-existing domain, this should be transferred to the CNCF -during their onboarding process. +during their onboarding process. To transfer a domain, please open an [LF +support desk][] ticket (Project Support Services → Domains & DNS → Transfer +Domain(s)). -If a project is new and does not have a domain name, they should open a -[CNCF Service Desk](https://github.com/cncf/servicedesk) ticket to arrange for -one. +If a project is new and does not have a domain name, they should open a [CNCF +service desk][] ticket to arrange for one. In most cases, we prefer to manage domains for project websites using Netlify DNS. -At the moment, [@caniszczyk][] manages domain transfers. - ### Netlify DNS domains When using Netlify DNS, we delegate the domain from another provider to Netlify @@ -47,8 +46,7 @@ more. Some projects have more than one domain name and want all of them to point to their website. In this case, read [Multiple Domains](https://docs.netlify.com/domains-https/custom-domains/multiple-domains/) -for more information, and ask them to open a -[CNCF Service Desk](https://github.com/cncf/servicedesk) ticket. +for more information, and ask them to open a [CNCF service desk][] ticket. ### Domains that don't point to Netlify websites @@ -58,3 +56,6 @@ used for, among other things, email addresses. Issues related to these should be forwarded on to Linux Foundation IT staff. [@caniszczyk]: https://github.com/caniszczyk +[@nate-double-u]: https://github.com/nate-double-u +[CNCF service desk]: https://servicedesk.cncf.io/ +[LF support desk]: https://support.linuxfoundation.org/ diff --git a/docs/services.md b/docs/services.md index b5c9d7e..5d91e4f 100644 --- a/docs/services.md +++ b/docs/services.md @@ -4,7 +4,7 @@ The CNCF provides technical writing and documentation website services for all its projects. All requests are subject to approval by the CNCF and should be submitted through -the [CNCF service desk](https://servicedesk.cncf.io). +the [CNCF service desk][]. ## Docs assessment @@ -38,6 +38,8 @@ Netlify installed/added to this repository A list of key maintainer(s) who should have access to Netlify A decision on whether your project will use CNCF’s CLA or Github’s DCO for committer verification. +For more information, see [Netlify and domain setup](netlify-domains-setup.md). + ## Techdocs office hours **What it is:** An hour long open meeting with CNCF’s technical writers where @@ -113,3 +115,5 @@ statement of work for a contractor and plan accordingly. > Note: Longer technical writer engagements are subject to team availability and > CNCF priorities. Availability is not guaranteed. + +[CNCF service desk]: https://servicedesk.cncf.io/ From 80c3791014cb4965e73047eda6c8dcd67d8cae90 Mon Sep 17 00:00:00 2001 From: Nate W Date: Wed, 12 Mar 2025 12:00:58 -0700 Subject: [PATCH 002/104] Add trademark guidance for Series LLCs to website guidelines (#298) * adding guidance for Series LLCs Signed-off-by: Nate W * Update docs/website-guidelines-checklist.md Signed-off-by: Nate W * Update docs/website-guidelines-checklist.md Co-authored-by: Patrice Chalin Signed-off-by: Nate W * updating formatting after applying edit Signed-off-by: Nate W --------- Signed-off-by: Nate W Co-authored-by: Patrice Chalin Signed-off-by: Bruce Hamilton --- docs/website-guidelines-checklist.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index 050fcd5..685a4f6 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -1,7 +1,7 @@ # CNCF website guidelines checklist As per the -[CNCF Website Guidelines](https://github.com/cncf/foundation/blob/master/website-guidelines.md), +[CNCF Website Guidelines](https://github.com/cncf/foundation/blob/main/website-guidelines.md), the following should be present:
_Note_, not all of these are applicable to all projects @@ -37,12 +37,14 @@ all projects status) - [ ] CNCF logo near the bottom of their project homepage - [ ] _Optionally_ link to KubeCon + CloudNativeCon as the events approach -- [ ] 7. Page footer contents - - [ ] Trademark guidelines by either linking to Trademark Usage (directly or - via a "Terms of service" page), or by including the following text:
- "The Linux Foundation® (TLF) has registered trademarks and uses - trademarks. For a list of TLF trademarks, see - [Trademark Usage](https://www.linuxfoundation.org/trademark-usage/)". +- [ ] 7. Website footers: + - Must include **trademark guidelines** by either linking to [Trademark + Usage][] (directly or via a "Terms of service" page), or by including the + following text: "The Linux Foundation® (TLF) has registered trademarks and + uses trademarks. For a list of TLF trademarks, see [Trademark Usage][]". + - If your project has been converted to the Series LLC model (starting in + 2025), use the following **copyright statement**: "Copyright © + $PROJECT_NAME a Series of LF Projects, LLC." ## Community and license files @@ -51,3 +53,5 @@ The following files should be in the root of the repository: - [ ] [CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) - [ ] Guidelines for Contributors (CONTRIBUTING.md or similar) - [ ] [License file(s)](./repo-setup.md#license-files) + +[Trademark Usage]: https://www.linuxfoundation.org/trademark-usage/ From 5bdf29328fa5e19cfd513e2a0fa6ffc1e8a00d4b Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 17 Mar 2025 11:45:38 -0400 Subject: [PATCH 003/104] Use slack.cncf.io as canonical URL (#300) Signed-off-by: Bruce Hamilton --- .markdown-link-check.json | 3 +++ docs/localization/ja/README.md | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.markdown-link-check.json b/.markdown-link-check.json index 6a2ba8d..6356956 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -1,5 +1,8 @@ { "ignorePatterns": [ + { + "pattern": "^https://slack.cncf.io/?" + }, { "pattern": "^http://localhost" }, diff --git a/docs/localization/ja/README.md b/docs/localization/ja/README.md index b975d96..2a47790 100644 --- a/docs/localization/ja/README.md +++ b/docs/localization/ja/README.md @@ -70,4 +70,4 @@ CNCFのプロジェクト特有の用語については、原則として英語 CNCFのプロジェクトのローカライゼーションに関するコミュニケーションは、主に、[CNCFのSlack](https://cloud-native.slack.com)の[`#glossary-localization-japanese`](https://cloud-native.slack.com/archives/C057F81GFUG)チャンネルで行われています。ローカライゼーションに関する質問や提案がある場合は、こちらのチャンネルで議論してください。 -CNCFのSlackに参加していない場合は、[Community Inviterのサイト](https://communityinviter.com/apps/cloud-native/cncf)から参加できます。 +CNCFのSlackに参加していない場合は、[Community Inviterのサイト](https://slack.cncf.io)から参加できます。 From 4771e4fd3db8aa28e159b4ccc20a62387e943c2a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 17 Mar 2025 12:55:23 -0400 Subject: [PATCH 004/104] Docusaurus version of docs pages (#301) Signed-off-by: Bruce Hamilton --- .gitignore | 5 ++ .markdown-link-check.json | 2 +- .markdownlint.yaml | 1 + docs/analysis/criteria.md | 28 +++---- docs/analysis/templates/analysis.md | 2 +- docs/analysis/templates/implementation.md | 2 +- docs/analysis/templates/issue.md | 5 +- docs/analysis/templates/issues-list.md | 6 +- docs/analytics.md | 2 +- docs/repo-setup.md | 2 +- docs/versioning-documentation.md | 6 +- docusaurus.config.ts | 90 ++++++++++++++++++++++ package.json | 27 ++++++- sidebars.ts | 33 ++++++++ src/css/custom.css | 30 ++++++++ src/pages/index.mdx | 3 + static/img/cncf-icon-color.svg | 19 +++++ static/img/favicon.ico | Bin 0 -> 15086 bytes tsconfig.json | 8 ++ 19 files changed, 241 insertions(+), 30 deletions(-) create mode 100644 docusaurus.config.ts create mode 100644 sidebars.ts create mode 100644 src/css/custom.css create mode 100644 src/pages/index.mdx create mode 100644 static/img/cncf-icon-color.svg create mode 100644 static/img/favicon.ico create mode 100644 tsconfig.json diff --git a/.gitignore b/.gitignore index 7807fd3..5e24fb0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,8 @@ +# Docusaurus - cSpell:disable-next-line +.docusaurus +.cache-loader +/build + # npm assets node_modules/ package-lock.json diff --git a/.markdown-link-check.json b/.markdown-link-check.json index 6356956..b595fba 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -15,5 +15,5 @@ ], "timeout": "3s", "retryOn429": true, - "aliveStatusCodes": [200, 206] + "aliveStatusCodes": [200, 202, 206] } diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 6eb808e..4a8c589 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -3,3 +3,4 @@ list-marker-space: false no-inline-html: false +no-bare-urls: false diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 51c7870..8ce5107 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -40,7 +40,7 @@ We evaluate on the following: Example: -- +- https://prometheus.io/docs ### New user content @@ -66,7 +66,7 @@ We evaluate on the following: Example: -- +- https://falco.org/docs/getting-started/ ### Content maintainability & site mechanics @@ -90,7 +90,7 @@ We evaluate on the following: Example: -- +- https://kubernetes.io/docs/ ### Content creation processes @@ -107,9 +107,9 @@ We evaluate on the following: Examples: -- (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 ### Inclusive language @@ -140,7 +140,7 @@ We evaluate on the following: Example: -- +- https://prometheus.io/community/ ### Beginner friendly issue backlog @@ -154,7 +154,7 @@ We evaluate on the following: Example: -- (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 @@ -172,7 +172,7 @@ We evaluate on the following: Example: -- +- https://github.com/helm/community ### Project governance documentation @@ -184,7 +184,7 @@ We evaluate on the following: Example: -- +- https://github.com/envoyproxy/envoy/blob/main/GOVERNANCE.md ## Website @@ -327,7 +327,7 @@ We evaluate on the following: Example: -- +- https://helm.sh/ ### Case studies/social proof @@ -345,9 +345,9 @@ We evaluate on the following: Examples: -- (user testimonials) -- (logo wall) -- (blog) +- https://www.fluentd.org/testimonials (user testimonials) +- https://goharbor.io/ (logo wall) +- https://blog.rook.io/ (blog) ### SEO, Analytics and site-local search @@ -385,7 +385,7 @@ We evaluate on the following: Example: -- +- https://kubernetes.io ### Other diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index 524a7ee..5581011 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -1,6 +1,6 @@ --- title: _PROJECT_ Documentation Analysis -tags: _PROJECT_ +tags: [_PROJECT_] created: YYYY-MM-DD modified: YYYY-MM-DD author: _NAME_ (@_HANDLE_) diff --git a/docs/analysis/templates/implementation.md b/docs/analysis/templates/implementation.md index 0c89420..c4c7f05 100644 --- a/docs/analysis/templates/implementation.md +++ b/docs/analysis/templates/implementation.md @@ -1,6 +1,6 @@ --- title: Implementing _PROJECT_ Doc Improvements -tags: _PROJECT_ +tags: [_PROJECT_] --- diff --git a/docs/analysis/templates/issue.md b/docs/analysis/templates/issue.md index a1d81d0..b3da121 100644 --- a/docs/analysis/templates/issue.md +++ b/docs/analysis/templates/issue.md @@ -1,6 +1,6 @@ --- title: _PROJECT_ Issue -tags: _PROJECT_ +tags: [_PROJECT_] --- > AUTHOR NOTE: This template provides one possible format for the individual @@ -29,8 +29,7 @@ Type: This issue tracks recommended changes resulting from an analysis of the etcd documentation commissioned by CNCF. The analysis and supporting documents are -here: under -`00NN-project`. +here: https://github.com/cncf/techdocs/tree/main/analyses under `00NN-project`. ## Possible Implementation diff --git a/docs/analysis/templates/issues-list.md b/docs/analysis/templates/issues-list.md index 49c8742..89c251c 100644 --- a/docs/analysis/templates/issues-list.md +++ b/docs/analysis/templates/issues-list.md @@ -1,6 +1,6 @@ --- title: _PROJECT_ Umbrella Issue and Issues List -tags: _PROJECT_ +tags: [_PROJECT_] --- ## Overview @@ -21,11 +21,11 @@ tags: _PROJECT_ This issue tracks recommended changes resulting from an analysis of the _PROJECT_ documentation commissioned by CNCF. The analysis and supporting -documents are here: under +documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `00NN-project`. The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo: - +https://github.com/cncf/techdocs/issues ## Umbrella issue diff --git a/docs/analytics.md b/docs/analytics.md index 2e7d5e7..6ece103 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -93,7 +93,7 @@ Follow these steps: measurement ID. Continuing from the previous step: - Select **Go to your GA4 property** from the **GA4 Setup Assistant** view - of your UA property.
This will open an analytics console onto your GA4 + of your UA property.
This will open an analytics console onto your GA4 site tag. Perform the remaining steps from your GA4 console. - Select **Admin** > **Data stream** - Select the (only) data stream to view its details. diff --git a/docs/repo-setup.md b/docs/repo-setup.md index f3ee269..e58fb20 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -1,5 +1,5 @@ --- -cSpell:ignore cncf +cSpell:ignore: cncf --- # Repository setup diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md index 5acdc30..2a17b22 100644 --- a/docs/versioning-documentation.md +++ b/docs/versioning-documentation.md @@ -1,6 +1,6 @@ --- # prettier-ignore -cSpell:ignore Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi +cSpell:ignore: Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi --- # Technical Documentation Versioning with Hugo & Netlify @@ -161,7 +161,7 @@ Scores high on: Same style of dropdown function as above, but made simpler because of the configuration: - +https://github.com/kubernetes/website/blob/main/layouts/partials/navbar-version-selector.html ```html
+https://github.com/kubernetes/website/blob/main/hugo.toml ```toml [[params.versions]] diff --git a/docusaurus.config.ts b/docusaurus.config.ts new file mode 100644 index 0000000..d82780f --- /dev/null +++ b/docusaurus.config.ts @@ -0,0 +1,90 @@ +// cSpell:ignore cncf + +import { themes as prismThemes } from 'prism-react-renderer'; +import type { Config } from '@docusaurus/types'; +import type * as Preset from '@docusaurus/preset-classic'; + +const title = 'CNCF TechDocs'; +const repo = 'https://github.com/cncf/techdocs'; + +const config: Config = { + title, + // tagline: '', + favicon: + 'https://www.cncf.io/wp-content/themes/cncf-twenty-two/images/favicon.ico', // TODO: localize? + + // Production URL: + url: 'https://techdocs.netlify.app/', // TODO + baseUrl: '/', + + // GitHub pages deployment config. TODO: this still useful? + organizationName: 'cncf', + projectName: 'techdocs', + + onBrokenLinks: 'warn', // TODO: 'error' or 'throw' once we've fixed all links + onBrokenMarkdownLinks: 'warn', + + i18n: { + defaultLocale: 'en', + locales: ['en'], + }, + + presets: [ + [ + 'classic', + { + docs: { + sidebarPath: './sidebars.ts', + editUrl: `${repo}/tree/main`, + }, + theme: { + customCss: './src/css/custom.css', + }, + } satisfies Preset.Options, + ], + ], + + themeConfig: { + // TODO: Replace with your project's social card + // image: 'img/docusaurus-social-card.jpg', + navbar: { + title, + logo: { + alt: 'Logo', + src: 'img/cncf-icon-color.svg', + }, + items: [ + { + type: 'docSidebar', + sidebarId: 'docSidebar', + position: 'left', + label: 'Docs', + }, + ], + }, + footer: { + style: 'dark', + links: [ + { + label: 'Privacy', + href: 'https://www.linuxfoundation.org/legal/privacy-policy', + }, + { + label: 'Trademarks', + href: 'https://www.linuxfoundation.org/legal/trademark-usage', + }, + { + label: 'GitHub', + href: repo, + }, + ], + copyright: `Copyright © ${title} Authors ${new Date().getFullYear()} `, + }, + prism: { + theme: prismThemes.github, + darkTheme: prismThemes.dracula, + }, + } satisfies Preset.ThemeConfig, +}; + +export default config; diff --git a/package.json b/package.json index 1bf1be2..fa7cfe8 100644 --- a/package.json +++ b/package.json @@ -24,18 +24,41 @@ "fix": "npm run seq -- $(npm -s run _list:fix:*)", "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ", "test": "npm run check", - "update:pkgs": "npx npm-check-updates -u" + "update:pkgs": "npx npm-check-updates -u", + "docusaurus": "docusaurus", + "start": "docusaurus start", + "build": "docusaurus build", + "swizzle": "docusaurus swizzle", + "deploy": "docusaurus deploy", + "clear": "docusaurus clear", + "serve": "docusaurus serve", + "write-translations": "docusaurus write-translations", + "write-heading-ids": "docusaurus write-heading-ids", + "typecheck": "tsc" }, "author": "CNCF", "license": "CC-BY-4.0", "NOTE": "We've pinned markdown-link-check to 3.12.2 due to a bug in 3.13.x stream, both in the devDeps below and the check:links script above. For details, see https://github.com/tcort/markdown-link-check/issues/369.", + "dependencies": { + "@docusaurus/core": "3.7.0", + "@docusaurus/preset-classic": "3.7.0", + "@mdx-js/react": "^3.0.0", + "clsx": "^2.0.0", + "prism-react-renderer": "^2.3.0", + "react": "^19.0.0", + "react-dom": "^19.0.0" + }, "devDependencies": { "cspell": "^8.17.5", "markdown-link-check": "3.12.2", "markdownlint": "^0.37.4", "markdownlint-cli": "^0.44.0", "npm-check-updates": "^17.1.15", - "prettier": "^3.5.2" + "prettier": "^3.5.2", + "@docusaurus/module-type-aliases": "3.7.0", + "@docusaurus/tsconfig": "3.7.0", + "@docusaurus/types": "3.7.0", + "typescript": "~5.6.2" }, "private": true, "spelling": "cSpell:ignore ACMR loglevel pkgs -", diff --git a/sidebars.ts b/sidebars.ts new file mode 100644 index 0000000..df293d7 --- /dev/null +++ b/sidebars.ts @@ -0,0 +1,33 @@ +import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; + +// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) + +/** + * Creating a sidebar enables you to: + - create an ordered group of docs + - render a sidebar for each doc of that group + - provide next/previous navigation + + The sidebars can be generated from the filesystem, or explicitly defined here. + + Create as many sidebars as you want. + */ +const sidebars: SidebarsConfig = { + // By default, Docusaurus generates a sidebar from the docs folder structure + docSidebar: [{ type: 'autogenerated', dirName: '.' }], + + // But you can create a sidebar manually + /* + tutorialSidebar: [ + 'intro', + 'hello', + { + type: 'category', + label: 'Tutorial', + items: ['tutorial-basics/create-a-document'], + }, + ], + */ +}; + +export default sidebars; diff --git a/src/css/custom.css b/src/css/custom.css new file mode 100644 index 0000000..2bc6a4c --- /dev/null +++ b/src/css/custom.css @@ -0,0 +1,30 @@ +/** + * Any CSS included here will be global. The classic template + * bundles Infima by default. Infima is a CSS framework designed to + * work well for content-centric websites. + */ + +/* You can override the default Infima variables here. */ +:root { + --ifm-color-primary: #2e8555; + --ifm-color-primary-dark: #29784c; + --ifm-color-primary-darker: #277148; + --ifm-color-primary-darkest: #205d3b; + --ifm-color-primary-light: #33925d; + --ifm-color-primary-lighter: #359962; + --ifm-color-primary-lightest: #3cad6e; + --ifm-code-font-size: 95%; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); +} + +/* For readability concerns, you should choose a lighter palette in dark mode. */ +[data-theme='dark'] { + --ifm-color-primary: #25c2a0; + --ifm-color-primary-dark: #21af90; + --ifm-color-primary-darker: #1fa588; + --ifm-color-primary-darkest: #1a8870; + --ifm-color-primary-light: #29d5b0; + --ifm-color-primary-lighter: #32d8b4; + --ifm-color-primary-lightest: #4fddbf; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); +} diff --git a/src/pages/index.mdx b/src/pages/index.mdx new file mode 100644 index 0000000..28955dd --- /dev/null +++ b/src/pages/index.mdx @@ -0,0 +1,3 @@ +import README from '../../README.md'; + + diff --git a/static/img/cncf-icon-color.svg b/static/img/cncf-icon-color.svg new file mode 100644 index 0000000..3000a4f --- /dev/null +++ b/static/img/cncf-icon-color.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + diff --git a/static/img/favicon.ico b/static/img/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..a68a7ca9b9e0e54a8b3b526c46a5189b8f1b18f6 GIT binary patch literal 15086 zcmeHOF>4%06ni}nVZ|0*_qj$z0n<5xA1tkGxOf}?VH)R z?`H1+)*yqMH-U5)etsX|BLL`jr{~uJUQ*k2(%k>WHGmx&@Bxh>6WAu<_SLb9z-31O zcVHAP-@p3|&-O>r^4GV|qOq9YE^|K3Ix^MjQ_g)u$^3Pz4?(M_M{r!5-3;O&Tww?EPi}?HURb9KdCJ*;o+g;dN zCV#=5V{GSEYOCYU{WLdA<3BI=W%5tKeOdfdabE`il-w81KQ;H({JAFNy2=vvS9geO zu$}>RHlcnzd-%lWAkX zCRw-A`s5ht63>6p+{JaJb&6-yYZGd>-!Xf0_K}<-Sb* zDY!3-e=6?F;GdHFqWP!ho|?bN1-zfch4zDGpL_qXMgDZ< z)LGl2-(Rfwo6qM}{LOgOy+3-B*AKm$q5JYMT4es=926&QumbOoIPb2GRRm%pfa0Kf z+tMfOWE~({=NH+8?efXG)aM-#yLu>LZ~ zA?xiNd#tx|1lE8T*I2LN6b3*Ha_jjtccFkWK|C;40x@iq=8`!kB?XnYm%=I-lep77b zlNvt;J2ieRc4PcM?-!^E+qn*j&+|^wV84-lh_RY)EIxZ=`!3g!e5X_GCp^#kvd8M@ zX1t_t!m6%6D~~ySMB;m}F$Ul85rJ>mS=ZJS-}FJbr6GRB&d3vD4r=3H@zEBW?56ub z9CsxR@YUGn*Uf8&_w*%BY1baV^r5fE&}WHn+O@+seS|ReJ~40BTs6Yi^8I&Zp0Q$K$MU*nz%&sA#t%5~Q~2U6n4VvAUD zJrr4g2+npLWyE}dV(r;AnQf!aWAV-LvNpd;_3z@Ze{tWx0(*_FJo6^E$^8PvAwXtJ zanb1)lZ}3HzS%FvISKZQW6X-Zi>&BOvZtN%Y`8JbhMVL5F#oqd#Q*w7NH&(8?U&CL zF7H#&U(Cc_#bxhPSUCvs;NwE8Nn~yE(~Vjv`F#Ptqjs972a@srMCom<}p&k!0e?0z|4-b@o zwSLrjY0I%F=U%kC=5LylmAw|L*}9qa1?&}%7VF>4(c=DL?wZi`l7C~I;xvy&1n8|v jdHgoOqgy0*0S2!C`bPk}BzwODJmz+iAE-}_XWRb)Px+3q literal 0 HcmV?d00001 diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..920d7a6 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,8 @@ +{ + // This file is not used in compilation. It is here just for a nice editor experience. + "extends": "@docusaurus/tsconfig", + "compilerOptions": { + "baseUrl": "." + }, + "exclude": [".docusaurus", "build"] +} From 4e04c4da1570a699f66ea192d93fb756c27d2c31 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 18 Mar 2025 11:24:18 -0400 Subject: [PATCH 005/104] Adjust markdown syntax of analyses pages (#302) Signed-off-by: Bruce Hamilton --- .markdown-link-check.json | 4 + analyses/0002-notary-project.md | 2 +- analyses/0005-fluxcd.md | 4 +- analyses/0006-gateway-api.md | 2 +- analyses/0007-porter.md | 12 +-- analyses/0008-backstage/README.md | 2 +- analyses/0008-backstage/backstage-analysis.md | 2 +- .../backstage-implementation.md | 2 +- .../0009-in-toto/in-toto-implementation.md | 5 +- analyses/0010-etcd/README.md | 2 +- analyses/0010-etcd/etcd-analysis.md | 2 +- analyses/0010-etcd/etcd-implementation.md | 2 +- analyses/0011-keda/README.md | 2 +- analyses/0011-keda/keda-analysis.md | 22 +++--- analyses/0011-keda/keda-implementation.md | 24 +++--- analyses/0011-keda/keda-issues.md | 42 +++++------ analyses/0012-TUF/analysis.md | 25 +++---- analyses/0012-TUF/issues.md | 6 +- .../0013-litmuschaos/litmuschaos-analysis.md | 26 +++---- .../litmuschaos-implementation.md | 2 +- .../0013-litmuschaos/litmuschaos-issues.md | 74 +++++++++---------- 21 files changed, 133 insertions(+), 131 deletions(-) diff --git a/.markdown-link-check.json b/.markdown-link-check.json index b595fba..ecbf492 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -11,6 +11,10 @@ }, { "pattern": "\\?no-link-check$" + }, + { + "why": "Temporary: due to scheduled maintenance", + "pattern": "https://www.usenix.org" } ], "timeout": "3s", diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md index a36e23a..917390e 100644 --- a/analyses/0002-notary-project.md +++ b/analyses/0002-notary-project.md @@ -199,7 +199,7 @@ Criteria - Letting new users know where to get help - Complete the governance work started here: - + https://github.com/notaryproject/specifications/issues/55 https://github.com/notaryproject/notaryproject/pull/78, and add it to a governance page (or section) on the website. diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md index 6f42aad..2e0a37e 100644 --- a/analyses/0005-fluxcd.md +++ b/analyses/0005-fluxcd.md @@ -5,7 +5,7 @@ cSpell:ignore: celestehorgan Horgan # Assessment template Prepared by: Celeste Horgan -([@celestehorgan](https://github.com/cncf/techdocs))
Date: 2021-11-30 +([@celestehorgan](https://github.com/cncf/techdocs))
Date: 2021-11-30 ## Introduction @@ -159,7 +159,7 @@ Scale: - [This file](https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh) is _very_ fragile, as it points to specific files at their - and + https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh and seems to have the potential to make the site build succeed but with unpredictable results. - Consider implementing [Hugo Modules](https://gohugo.io/hugo-modules/) to diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md index f346292..fcfd42a 100644 --- a/analyses/0006-gateway-api.md +++ b/analyses/0006-gateway-api.md @@ -5,7 +5,7 @@ cSpell:ignore: Meha Bhalodiya mehabhalodiya kubernetes # Assessment: Project Kubernetes Gateway API Prepared by: Meha Bhalodiya -([@mehabhalodiya](https://github.com/mehabhalodiya))
Date: 2021-03-03 +([@mehabhalodiya](https://github.com/mehabhalodiya))
Date: 2021-03-03 ## Introduction diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md index 5aaf385..88c52b9 100644 --- a/analyses/0007-porter.md +++ b/analyses/0007-porter.md @@ -16,11 +16,11 @@ Date: 2023-04-07 Resources: - [Meeting notes](https://docs.google.com/document/d/12OGtSaUtlc7OA_iPnUvmVaiKg8yM7_QBzFnMgoHvnLw?no-link-check) -- Website: +- Website: https://getporter.org - Repos: - - Main site: . Content is in `docs`. + - Main site: https://github.com/getporter/porter. Content is in `docs`. - [Operator site](https://getporter.org/operator): - + https://github.com/getporter/operator ## Introduction @@ -69,8 +69,8 @@ Scale: difference between desired state and operator? maybe the operator one needs to be in Get Started) - - - - + - https://getporter.org/quickstart/desired-state/ + - https://getporter.org/operator/quickstart/ - Mixins & Plugins sections duplicated in sidebar (and could potentially be organized under Concepts?) @@ -155,7 +155,7 @@ Scale: - Move the website sourcefile to a separate "website" directory. That way, we create a good separation of concern. A good example is - . + https://github.com/thanos-io/thanos. - The porter's docs should be searchable. - Create a version picker (dropdown) to make search easily discoverable for users. diff --git a/analyses/0008-backstage/README.md b/analyses/0008-backstage/README.md index eac162e..29e1428 100644 --- a/analyses/0008-backstage/README.md +++ b/analyses/0008-backstage/README.md @@ -1,6 +1,6 @@ --- title: Backstage TechDocs Analysis -tags: backstage +tags: [backstage] --- - [Backstage Doc Analysis](backstage-analysis.md) - Analyzes the existing diff --git a/analyses/0008-backstage/backstage-analysis.md b/analyses/0008-backstage/backstage-analysis.md index fb0570c..eee1d3c 100644 --- a/analyses/0008-backstage/backstage-analysis.md +++ b/analyses/0008-backstage/backstage-analysis.md @@ -1,6 +1,6 @@ --- title: Backstage Documentation Analysis -tags: backstage +tags: [backstage] created: 2023-09-01 modified: 2023-11-28 author: Dave Welsch (@dwelsch-esi) diff --git a/analyses/0008-backstage/backstage-implementation.md b/analyses/0008-backstage/backstage-implementation.md index c0a3da2..0668d23 100644 --- a/analyses/0008-backstage/backstage-implementation.md +++ b/analyses/0008-backstage/backstage-implementation.md @@ -1,6 +1,6 @@ --- title: Implementing Backstage Doc Improvements -tags: backstage +tags: [backstage] cSpell:ignore: rigeur runbooks toolkits --- diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md index 98e9e11..b5b9c08 100644 --- a/analyses/0009-in-toto/in-toto-implementation.md +++ b/analyses/0009-in-toto/in-toto-implementation.md @@ -89,9 +89,8 @@ following general plan. the website, as: - [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) - (compare content to and current website - About - create versions of increasing depth to address to specific - audiences) + (compare content to https://in-toto.io/in-toto and current website About - + create versions of increasing depth to address to specific audiences) - [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology) (convert to alphabetized table) - [Workflow/Personas](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) diff --git a/analyses/0010-etcd/README.md b/analyses/0010-etcd/README.md index cb3ff7a..a6e3ae8 100644 --- a/analyses/0010-etcd/README.md +++ b/analyses/0010-etcd/README.md @@ -1,6 +1,6 @@ --- title: etcd TechDocs Analysis -tags: etcd +tags: [etcd] --- - [etcd Doc Analysis](etcd-analysis.md) - Analyzes the existing etcd diff --git a/analyses/0010-etcd/etcd-analysis.md b/analyses/0010-etcd/etcd-analysis.md index c36d5ce..a9d7818 100644 --- a/analyses/0010-etcd/etcd-analysis.md +++ b/analyses/0010-etcd/etcd-analysis.md @@ -1,6 +1,6 @@ --- title: etcd Documentation Analysis -tags: etcd +tags: [etcd] created: 2023-09-01 modified: 2024-01-08 author: Dave Welsch (@dwelsch-esi) diff --git a/analyses/0010-etcd/etcd-implementation.md b/analyses/0010-etcd/etcd-implementation.md index 3bee2d8..409cee3 100644 --- a/analyses/0010-etcd/etcd-implementation.md +++ b/analyses/0010-etcd/etcd-implementation.md @@ -1,6 +1,6 @@ --- title: Implementing etcd Doc Improvements -tags: etcd +tags: [etcd] --- # Introduction diff --git a/analyses/0011-keda/README.md b/analyses/0011-keda/README.md index 1409d20..c5fe248 100644 --- a/analyses/0011-keda/README.md +++ b/analyses/0011-keda/README.md @@ -1,6 +1,6 @@ --- title: KEDA TechDocs Analysis -tags: KEDA +tags: [KEDA] --- - [KEDA Doc Analysis](keda-analysis.md) - Analyzes the existing KEDA diff --git a/analyses/0011-keda/keda-analysis.md b/analyses/0011-keda/keda-analysis.md index adcaf5e..e327861 100644 --- a/analyses/0011-keda/keda-analysis.md +++ b/analyses/0011-keda/keda-analysis.md @@ -48,15 +48,15 @@ Netlify platform. The site's code is stored on the KEDA GitHub repo. **In scope:** -- Website: -- Documentation: -- Website repo: -- Governance repo: -- Main project contributor info: +- Website: https://keda.sh +- Documentation: https://keda.sh/docs +- Website repo: https://github.com/kedacore/keda-docs +- Governance repo: https://github.com/kedacore/governance +- Main project contributor info: https://github.com/kedacore/keda **Out of scope:** -- Other KEDA repos under +- Other KEDA repos under https://github.com/kedacore/ ## How this document is organized @@ -235,12 +235,12 @@ The documentation includes some examples of [**non-inclusive language**](https://inclusivenaming.org/). For example: - "easily", "simple", "simply", etc. - - - - - - + - https://keda.sh/docs/2.13/deploy/ + - https://keda.sh/docs/2.13/deploy/#uninstall-3 + - https://keda.sh/docs/2.13/concepts/scaling-deployments/#triggers - "master" node - - - - + - https://keda.sh/docs/2.13/troubleshooting/#google-kubernetes-engine-gke + - https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/#authentication-parameters ## Recommendations diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index 134fc01..695b6cd 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -77,7 +77,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename current "KEDA Documentation" heading) - [Deploying KEDA](https://keda.sh/docs/2.13/deploy/) - - Prerequisites () + - Prerequisites (https://keda.sh/docs/2.13/operate/cluster/#requirements) - [Deploying with Helm](?no-link-check#helm) - [Installing](?no-link-check#install) - [Uninstalling](?no-link-check#uninstall) @@ -92,7 +92,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [Uninstalling](?no-link-check#uninstall-3) - Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like - ) + https://github.com/kedacore/sample-hello-world-azure-functions) - [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename current "Operate") - How to set up a scaler (a more detailed procedure than the example used in @@ -103,13 +103,13 @@ Here is a proposed outline for the tech doc Table of Contents: - ... and so on. - [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/) - Prevention Rules - () + (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules) - Validation Enforcement - [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - Except sections that are purely reference info, for example: - - - - - - + - https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility + - https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity + - https://keda.sh/docs/2.13/operate/cluster/#firewall - [Integrating with OpenTelemetry Collector (Experimental)](https://keda.sh/docs/2.13/integrations/opentelemetry/) - [Integrating with Prometheus](https://keda.sh/docs/2.13/integrations/prometheus/) - [Using the KEDA Metrics Server](https://keda.sh/docs/2.13/operate/metrics-server/) @@ -119,11 +119,11 @@ Here is a proposed outline for the tech doc Table of Contents: - [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current "Migration Guide") - Caching Metrics - () + (https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics) - Pausing Autoscaling of deployments - () + (https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling) - Pausing Autoscaling of jobs - () + (https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling) - [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/), `/docs/2.13/troubleshooting/` - Reference @@ -132,9 +132,9 @@ Here is a proposed outline for the tech doc Table of Contents: - ... - [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/) - Scaled Object specification (from "Concepts"; - ) + https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec) - ScaledJob specification - () + (https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec) - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... @@ -211,7 +211,7 @@ annotated to illustrate this point: - [Uninstalling](?no-link-check#uninstall-3) - Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like - ) _analogous + https://github.com/kedacore/sample-hello-world-azure-functions) _analogous to a "Hello World" exercise in programming language or API guides_ # Update the doc content creation instructions diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index f633ae0..5eb497b 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -99,7 +99,7 @@ into multiple pages, one for each procedure. - [Uninstalling](?no-link-check#uninstall-3) - Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like - ) _analogous + https://github.com/kedacore/sample-hello-world-azure-functions) _analogous to a "Hello World" exercise in programming language or API guides_ ## Issue: Update the Operator Guide @@ -111,9 +111,9 @@ Some guidelines: - Move "Troubleshooting" to the end of the Operator Guide. - Relocate sections that are purely reference information, including these sections in [Cluster](https://keda.sh/docs/2.13/operate/cluster/): - - - - - - + - https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility + - https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity + - https://keda.sh/docs/2.13/operate/cluster/#firewall - Break up long pages containing several topics. Aim for one major topic per page. For example, all HTTP-related headings on the [Cluster](https://keda.sh/docs/2.13/operate/cluster/) page could go on one @@ -133,7 +133,7 @@ or provide a starting point. - ... and so on. - [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/) - Prevention Rules - () + (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules) - Validation Enforcement - [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - (Relocate sections that are purely reference info) @@ -151,11 +151,11 @@ or provide a starting point. - [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current "Migration Guide") - Caching Metrics - () + (https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics) - Pausing Autoscaling of deployments - () + (https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling) - Pausing Autoscaling of jobs - () + (https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling) - [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/) `/docs/2.13/troubleshooting/` @@ -175,9 +175,9 @@ or provide a starting point. - ... - [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/) - Scaled Object specification (from "Concepts"; - ) + https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec) - ScaledJob specification - () + (https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec) - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... @@ -202,17 +202,17 @@ information. Some of these pages might appear in other issues suggesting that they be revised or relocated. If this creates contradictory recommendations, some judgement might be required to rearrange things. -| Page Title | URL | Notes | -| ------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Deploying KEDA | | Page is all install and uninstall tasks, but put each install procedure on its own page. Make this page an intro and index. | -| Scaling Deployments, StatefulSets and Custom Resources | | The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task. | -| Scaling Jobs | | "ScaledJob spec" is reference information. | -| Authentication | | Deliberately discuss the three patterns listed at the top of the page. This entire page might be better written as a task-based how-to guide. | -| External Scalers | | "Implementing KEDA external scaler GRPC interface" is a series of tasks. The steps after the first 2 are choices -- Describe the task of downloading `externalscaler.proto` and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently. | -| Troubleshooting | | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". | -| Cluster | | See the "Update the Operator Guide" issue | -| Events | | This is reference information. | -| Integrate with Prometheus | | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". | +| Page Title | URL | Notes | +| ------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Deploying KEDA | https://keda.sh/docs/2.13/deploy/ | Page is all install and uninstall tasks, but put each install procedure on its own page. Make this page an intro and index. | +| Scaling Deployments, StatefulSets and Custom Resources | https://keda.sh/docs/2.13/concepts/scaling-deployments/ | The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task. | +| Scaling Jobs | https://keda.sh/docs/2.13/concepts/scaling-jobs/ | "ScaledJob spec" is reference information. | +| Authentication | https://keda.sh/docs/2.13/concepts/authentication/ | Deliberately discuss the three patterns listed at the top of the page. This entire page might be better written as a task-based how-to guide. | +| External Scalers | https://keda.sh/docs/2.13/concepts/external-scalers/ | "Implementing KEDA external scaler GRPC interface" is a series of tasks. The steps after the first 2 are choices -- Describe the task of downloading `externalscaler.proto` and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently. | +| Troubleshooting | https://keda.sh/docs/2.13/concepts/troubleshooting/ | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". | +| Cluster | https://keda.sh/docs/2.13/operate/cluster/ | See the "Update the Operator Guide" issue | +| Events | https://keda.sh/docs/2.13/operate/events/ | This is reference information. | +| Integrate with Prometheus | https://keda.sh/docs/2.13/integrations/prometheus/ | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". | # Write a Glossary diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index d68c4e4..d6438f5 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -1,6 +1,6 @@ --- title: TUF Documentation Analysis -tags: TUF +tags: [TUF] created: 2024-06-17 modified: YYYY-MM-DD author: Sandra Dindi (@Dindihub) @@ -48,25 +48,24 @@ is stored on the TUF GitHub repo. #### In scope -- Website and docs: -- Website repo: -- The TUF community repository: - +- Website and docs: https://theupdateframework.io +- Website repo: https://github.com/theupdateframework/theupdateframework.io +- The TUF community repository: https://github.com/theupdateframework/community - TUF specification repository: - -- TUF artwork repository: + https://github.com/theupdateframework/specification +- TUF artwork repository: https://github.com/theupdateframework/artwork - Python reference implementation repository: - + https://github.com/theupdateframework/python-tuf #### Out of scope - TUF Augmentation proposals repository: - -- python-tuf: -- go-tuf: + https://github.com/theupdateframework/taps +- python-tuf: https://theupdateframework.readthedocs.io +- go-tuf: https://pkg.go.dev/github.com/theupdateframework/go-tuf - tuf-on-ci: - -- RSTUF: + https://github.com/theupdateframework/tuf-on-ci?tab=readme-ov-file#documentation +- RSTUF: https://repository-service-tuf.readthedocs.io ### How this document is organized diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 9abe2c1..3faef04 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -7,9 +7,9 @@ cSpell:ignore: theupdateframework This issue tracks recommended changes resulting from an analysis of the TUF documentation commissioned by CNCF. The analysis and supporting documents are -here: under -`0012-TUF`.This is a master list of issues recommended in the TUF tech doc -analysis and implementation plan. +here: https://github.com/cncf/techdocs/tree/main/analyses under `0012-TUF`.This +is a master list of issues recommended in the TUF tech doc analysis and +implementation plan. ## Issues diff --git a/analyses/0013-litmuschaos/litmuschaos-analysis.md b/analyses/0013-litmuschaos/litmuschaos-analysis.md index ca7786f..0a935eb 100644 --- a/analyses/0013-litmuschaos/litmuschaos-analysis.md +++ b/analyses/0013-litmuschaos/litmuschaos-analysis.md @@ -1,6 +1,6 @@ --- title: LitmusChaos Documentation Analysis -tags: LitmusChaos +tags: [LitmusChaos] created: 2024-08-02 modified: 2024-10-09 author: Dave Welsch (@dwelsch-esi) @@ -54,17 +54,17 @@ GitHub repo. #### In scope -- Website: -- Website repo: -- Documentation repo: +- Website: https://litmuschaos.io/ +- Website repo: https://github.com/litmuschaos/litmus-website-2 +- Documentation repo: https://github.com/litmuschaos/litmus-docs/ - Main project repo (for governance and contributor docs): - + https://github.com/litmuschaos/litmus #### Out of scope -- Other LitmusChaos repos: +- Other LitmusChaos repos: https://github.com/litmuschaos/ - Litmus Software (a completely unrelated company and product based in - Massachusetts): + Massachusetts): https://litmus.com/ ### How this document is organized @@ -604,12 +604,12 @@ websites: -| Site | Repository | Tool or Stack | -| ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------ | -| [Project website](https://litmuschaos.io/) | | React/Next/Tailwind/SCSS | -| [Documentation website](https://docs.litmuschaos.io/) | | Docusaurus/Netlify | -| Tutorials | | Google Codelab? | -| [APIs][api-site] | | MkDocs | +| Site | Repository | Tool or Stack | +| ----------------------------------------------------- | -------------------------------------------------------- | ------------------------ | +| [Project website](https://litmuschaos.io/) | https://github.com/litmuschaos/litmus-website-2 | React/Next/Tailwind/SCSS | +| [Documentation website](https://docs.litmuschaos.io/) | https://github.com/litmuschaos/litmus-docs/ | Docusaurus/Netlify | +| Tutorials | https://github.com/litmuschaos/tutorials | Google Codelab? | +| [APIs][api-site] | https://github.com/litmuschaos/litmus/tree/master/mkdocs | MkDocs | diff --git a/analyses/0013-litmuschaos/litmuschaos-implementation.md b/analyses/0013-litmuschaos/litmuschaos-implementation.md index 5fe032b..427430b 100644 --- a/analyses/0013-litmuschaos/litmuschaos-implementation.md +++ b/analyses/0013-litmuschaos/litmuschaos-implementation.md @@ -1,6 +1,6 @@ --- title: Implementing LitmusChaos Doc Improvements -tags: LitmusChaos +tags: [LitmusChaos] created: 2024-10-24 author: Dave Welsch (@dwelsch-esi) cSpell:ignore: Welsch dwelsch diff --git a/analyses/0013-litmuschaos/litmuschaos-issues.md b/analyses/0013-litmuschaos/litmuschaos-issues.md index 3f1fc84..f0b38b9 100644 --- a/analyses/0013-litmuschaos/litmuschaos-issues.md +++ b/analyses/0013-litmuschaos/litmuschaos-issues.md @@ -38,20 +38,20 @@ websites. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation The following repos are affected: -| Repo URL | Description | Recommendation | -| ---------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | -| | The project website repo | Combine with the doc repo | -| | Documentation repo | Combine with website repo | -| | Another documentation repo, for docs before 2.0 | Move toward retiring and archiving. | -| | Previous website repo | Already archived. Include new repo URL in archive banner. | -| | Tutorials repo | Combine with documentation repo | +| Repo URL | Description | Recommendation | +| -------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | +| https://github.com/litmuschaos/litmus-website-2 | The project website repo | Combine with the doc repo | +| https://github.com/litmuschaos/litmus-docs | Documentation repo | Combine with website repo | +| https://github.com/litmuschaos/v1-litmus-docs | Another documentation repo, for docs before 2.0 | Move toward retiring and archiving. | +| https://github.com/litmuschaos/website-litmuschaos | Previous website repo | Already archived. Include new repo URL in archive banner. | +| https://github.com/litmuschaos/tutorials | Tutorials repo | Combine with documentation repo | ## Issue: Removed obsolete websites @@ -77,7 +77,7 @@ websites. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -85,10 +85,10 @@ are here: under **GraphicQL API** The following API is one of the first hits on a search of "Litmus Chaos API": -. +https://litmuschaos.github.io/litmus/graphql/v2.0.0/api.html. I'm not even sure where the doc repo is (it might be in the API's repo at -). It's clear this is a Litmus Chaos +https://github.com/litmuschaos/spectaql). It's clear this is a Litmus Chaos component, but not whether this documentation is current or what it is for -- there's no introduction or explanation of the API. @@ -143,7 +143,7 @@ This issue concerns instructional information. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -224,7 +224,7 @@ This issue concerns instructional information. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -277,7 +277,7 @@ This issue concerns conceptual information. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -315,7 +315,7 @@ This issue concerns organizing all documentation information. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -376,7 +376,7 @@ This issue concerns instructional information. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -421,7 +421,7 @@ This issue concerns conceptual information. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -458,7 +458,7 @@ This issue concerns meta-information (project community resources). This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -521,7 +521,7 @@ here. Some guidelines for writing procedures: This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -561,7 +561,7 @@ question. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -592,7 +592,7 @@ This issue concerns potentially all types of information. This issue tracks recommended changes resulting from an analysis of the Litmus Chaos documentation commissioned by CNCF. The analysis and supporting documents -are here: under +are here: https://github.com/cncf/techdocs/tree/main/analyses under `0013-litmuschaos`. ### Possible Implementation @@ -600,19 +600,19 @@ are here: under Here's a list of all the blog posts. Each should be evaluated for technical documentation content. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +- https://litmuschaos.io/blog/litmuschaos-is-joining-kubecon-cloudnativecon-north-america-2024-3blg +- https://litmuschaos.io/blog/introduction-to-k6-load-chaos-in-litmuschaos-4l2k +- https://litmuschaos.io/blog/introduction-to-http-chaos-in-litmuschaos-3hn +- https://litmuschaos.io/blog/gcp-iam-integration-for-litmuschaos-with-workload-identity-2eai +- https://litmuschaos.io/blog/frontend-optimization-at-litmuschaos-1p14 +- https://litmuschaos.io/blog/litmuschaos-in-2021-the-year-in-review-38cl +- https://litmuschaos.io/blog/how-to-contribute-blog-posts-for-litmuschaos-3cnp +- https://litmuschaos.io/blog/getting-started-with-litmus-2-0-in-google-kubernetes-engine-4obf +- https://litmuschaos.io/blog/part-2-a-beginner-s-practical-guide-to-containerisation-and-chaos-engineering-with-litmuschaos-2-0-253i +- https://litmuschaos.io/blog/part-1-a-beginner-s-practical-guide-to-containerisation-and-chaos-engineering-with-litmuschaos-2-0-3h5c +- https://litmuschaos.io/blog/litmuschaos-node-memory-hog-experiment-2nj6 +- https://litmuschaos.io/blog/analysing-chaos-workflows-with-litmus-portal-4e67 +- https://litmuschaos.io/blog/chaos-engineering-with-litmus-portal-on-okteto-cloud-3g57 +- https://litmuschaos.io/blog/how-to-use-react-hooks-in-apollo-client-for-graphql-33bh +- https://litmuschaos.io/blog/declarative-approach-to-chaos-hypothesis-using-litmus-probes-5157 +- https://litmuschaos.io/blog/litmuschaos-gitlab-remote-templates-6l2 From fd94c4fd5303cfdb4f98618a067fe21baffd3561 Mon Sep 17 00:00:00 2001 From: Nate W Date: Tue, 18 Mar 2025 17:19:34 -0700 Subject: [PATCH 006/104] Update README.md Updating Nate W.'s role. Signed-off-by: Nate W Signed-off-by: Bruce Hamilton --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index be0b70e..2ad9c96 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,11 @@ 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 | +| GitHub ID | Role | +| -------------------------------------------------- | --------------------------------------- | +| [@chalin](https://github.com/chalin) | Senior technical writer | +| [@nate-double-u](https://github.com/nate-double-u) | Head of Mentoring & Documentation, CNCF | +| [@thisisobate](https://github.com/thisisobate) | Developer advocate | From 9dadc76171086e45d67c222a61c48065e2a93fcb Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 19 Mar 2025 07:31:07 -0400 Subject: [PATCH 007/104] Fix licenses (#305) Signed-off-by: Bruce Hamilton --- LICENSE | 599 ++++++++++++++++++++++++++++++++++----------------- LICENSE-CODE | 202 +++++++++++++++++ 2 files changed, 600 insertions(+), 201 deletions(-) create mode 100644 LICENSE-CODE diff --git a/LICENSE b/LICENSE index 261eeb9..219720c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,201 +1,398 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +Creative Commons Attribution 4.0 International + +https://creativecommons.org/licenses/by/4.0 + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. + diff --git a/LICENSE-CODE b/LICENSE-CODE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/LICENSE-CODE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. From 2e862c517628c03f4bb461f8a9d5dfdb8aac7c05 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 19 Mar 2025 07:47:00 -0400 Subject: [PATCH 008/104] Add links to licenses to README and site footer (#306) Signed-off-by: Bruce Hamilton --- README.md | 5 +++++ docusaurus.config.ts | 4 ++++ 2 files changed, 9 insertions(+) diff --git a/README.md b/README.md index 2ad9c96..b49acfc 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,11 @@ The full-time staff of the CNCF Tech Docs team is: Various consultants and volunteers also contribute to CNCF Tech Docs projects. +## Licenses + +- Documentation: [CC-BY-4.0](LICENSE) +- Code: [Apache-2.0](LICENSE-CODE) + [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours [Zoom meeting 95471930872]: diff --git a/docusaurus.config.ts b/docusaurus.config.ts index d82780f..8db0e5c 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -65,6 +65,10 @@ const config: Config = { footer: { style: 'dark', links: [ + { + label: 'Licenses', + href: '/#licenses', + }, { label: 'Privacy', href: 'https://www.linuxfoundation.org/legal/privacy-policy', From 0ed9ebfc2438036b410c574c1d24ab034b94ab57 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 19 Mar 2025 11:32:28 -0400 Subject: [PATCH 009/104] Fix production URL (#308) Signed-off-by: Bruce Hamilton --- docusaurus.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 8db0e5c..b21d362 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -14,7 +14,7 @@ const config: Config = { 'https://www.cncf.io/wp-content/themes/cncf-twenty-two/images/favicon.ico', // TODO: localize? // Production URL: - url: 'https://techdocs.netlify.app/', // TODO + url: 'https://cncf-techdocs.netlify.app/', // FIXME if/once we get a domain baseUrl: '/', // GitHub pages deployment config. TODO: this still useful? From 9e34cf5fb78d29f601143b1711c7ee05dacba4ce Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 19 Mar 2025 13:09:15 -0400 Subject: [PATCH 010/104] Revise README, update PC role, add links (#309) * Revise README, update PC role, add links Signed-off-by: Patrice Chalin * Nate's feedback Signed-off-by: Patrice Chalin --------- Signed-off-by: Patrice Chalin Signed-off-by: Bruce Hamilton --- README.md | 60 ++++++++++++++++++++++++------------------------------- 1 file changed, 26 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index b49acfc..13a400e 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,29 @@ # CNCF TechDocs -This repository holds resources provided by the CNCF Technical Documentation -team. The repo contains the following directories: +This site contains resources provided by the CNCF Technical Documentation team, +including: -- `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: +- [Docs](docs) about building websites and developing technical documentation, + including recommended tools, best practices, how-tos, and evaluation + checklists. It provides 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. + - Seeking assistance from the CNCF TechDocs community. + - [Analyzing project documentation](docs/analysis/). +- [Analyses](analyses): a collection of documentation analyses of CNCF projects + performed by the TechDocs team. ## TechDocs Q&A -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 +The CNCF TechDocs team holds a [Zoom meeting][] to answer questions and discuss +anything to do with documentation. Meetings are held on the [fourth Wednesday of every month at 8am Pacific time][date-time]. -TechDocs Q&A (formerly called _Office Hours_) started on 30 September 2020. +- [Zoom meeting][] link +- [Meeting notes][] -### Meeting link - -- [Zoom meeting 95471930872] - -### Meeting notes - -We store ongoing meeting notes in a -[Google doc](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/). +> Formerly called _Office Hours_, TechDocs Q&A started on September +> 30, 2020. ## Assistance program for technical documentation @@ -39,20 +33,14 @@ documentation. For details, see the TechDocs ## CNCF TechDocs team -The full-time staff of the CNCF Tech Docs team is: +The full-time staff of the team is (in alphabetical order): - +- [Nate Waddington](https://github.com/nate-double-u) - Head of mentoring & + documentation +- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead +- [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate -| GitHub ID | Role | -| -------------------------------------------------- | --------------------------------------- | -| [@chalin](https://github.com/chalin) | Senior technical writer | -| [@nate-double-u](https://github.com/nate-double-u) | Head of Mentoring & Documentation, CNCF | -| [@thisisobate](https://github.com/thisisobate) | Developer advocate | - - - - -Various consultants and volunteers also contribute to CNCF Tech Docs projects. +Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses @@ -61,5 +49,9 @@ 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 -[Zoom meeting 95471930872]: +[Meeting notes]: + https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/ +[Zoom meeting]: https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e + + From 6448746fd3b570004c24868c08dd715d54884d81 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 19 Mar 2025 13:45:05 -0400 Subject: [PATCH 011/104] [CI] Use htmltest for link checking (#310) Signed-off-by: Bruce Hamilton --- .gitignore | 2 + .htmltest.yml | 12 + Makefile | 56 ++++ docs/analysis/howto.md | 2 +- docusaurus.config.ts | 2 + package.json | 6 +- static/refcache.json | 630 +++++++++++++++++++++++++++++++++++++++++ 7 files changed, 707 insertions(+), 3 deletions(-) create mode 100644 .htmltest.yml create mode 100644 Makefile create mode 100644 static/refcache.json diff --git a/.gitignore b/.gitignore index 5e24fb0..8665d05 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ # npm assets node_modules/ package-lock.json + +/tmp diff --git a/.htmltest.yml b/.htmltest.yml new file mode 100644 index 0000000..8594ce7 --- /dev/null +++ b/.htmltest.yml @@ -0,0 +1,12 @@ +# cSpell:ignore github +CacheExpires: 9000h # ~ 12 months +DirectoryPath: build +TestFilesConcurrently: true +IgnoreDirs: +IgnoreInternalURLs: # list of paths +IgnoreURLs: # list of regexes of URLs or path to be ignored + - \?no-link-check + # FIXME: temporary ignore rules + - assistance\.md + - LICENSE + - /analyses/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..709eb92 --- /dev/null +++ b/Makefile @@ -0,0 +1,56 @@ +# cSpell:ignore htmltest refcache +# Set REFCACHE to another value to disable htmltest refcache-file manipulation +REFCACHE?=refcache +HTMLTEST_DIR=tmp +HTMLTEST?=htmltest # Specify as make arg if different +HTMLTEST_ARGS?=--log-level 1 +LINK_CACHE_FILE?=refcache.json +LINK_CACHE_FILE_DEST_DIR?=static +LINK_CACHE_FILE_SRC_DIR?=$(HTMLTEST_DIR)/.htmltest + +# Use $(HTMLTEST) in PATH, if available; otherwise, we'll get a copy +ifeq (, $(shell which $(HTMLTEST))) +override HTMLTEST=$(HTMLTEST_DIR)/bin/htmltest +ifeq (, $(shell which $(HTMLTEST))) +GET_LINK_CHECKER_IF_NEEDED=get-link-checker +endif +endif + +default: + @echo "Make what? Target list:\n" + @make -rpn | grep '^[a-z]\S*:' | sed 's/://' | sort + +$(LINK_CACHE_FILE_SRC_DIR): + mkdir -p $(LINK_CACHE_FILE_SRC_DIR) + +$(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE): + mkdir -p $(LINK_CACHE_FILE_DEST_DIR) + echo '{}' > $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) + +refcache-restore: $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR) +ifeq (refcache, $(REFCACHE)) + cp $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_SRC_DIR)/ +else + @echo "SKIPPING refcache-restore" +endif + +refcache-save: +ifeq (refcache, $(REFCACHE)) + cp $(LINK_CACHE_FILE_SRC_DIR)/$(LINK_CACHE_FILE) $(LINK_CACHE_FILE_DEST_DIR)/ + npx prettier --prose-wrap=always --write $(LINK_CACHE_FILE_DEST_DIR)/$(LINK_CACHE_FILE) +else + @echo "SKIPPING refcache-save" +endif + +check-links: $(GET_LINK_CHECKER_IF_NEEDED) \ + refcache-restore check-links-only refcache-save + +check-links-only: + $(HTMLTEST) $(HTMLTEST_ARGS) + +clean: + rm -rf $(HTMLTEST_DIR) public/* resources + +get-link-checker: + rm -Rf $(HTMLTEST_DIR)/bin + curl https://htmltest.wjdp.uk | bash -s -- -b $(HTMLTEST_DIR)/bin diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index 22018b5..aea4e93 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -217,5 +217,5 @@ Create issues in the project documentation GitHub repository for: [analyses]: ../../analyses/ [criteria]: ./criteria.md [project maturity level]: https://www.cncf.io/project-metrics -[templates]: ./templates/ +[templates]: ./templates/README.md [issues list]: ./templates/issues-list.md diff --git a/docusaurus.config.ts b/docusaurus.config.ts index b21d362..96b5c27 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -24,6 +24,8 @@ const config: Config = { onBrokenLinks: 'warn', // TODO: 'error' or 'throw' once we've fixed all links onBrokenMarkdownLinks: 'warn', + trailingSlash: true, + i18n: { defaultLocale: 'en', locales: ['en'], diff --git a/package.json b/package.json index fa7cfe8..cf6d672 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,8 @@ "_check:format:any": "npx prettier --check --ignore-path ''", "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)", "_check:format": "npx prettier --check .", - "_check:links": "npx markdown-link-check --config .markdown-link-check.json", + "_check:links": "make --keep-going check-links", + "_check:links-md": "bash -c 'for f in *.md `find analyses -name \"*.md\"`; do npx markdown-link-check@3.12.2 --config .markdown-link-check.json -p -v $f || exit 1; done'", "_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", @@ -16,12 +17,13 @@ "_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": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx markdown-link-check@3.12.2 --config .markdown-link-check.json -p -v $f || exit 1; done'", + "check:links": "npm run _check:links", "check:markdown": "npm run _check:markdown:all", "check:spelling": "npx cspell --no-progress -c .cspell.yml analyses docs *.md", "check": "npm run seq -- $(npm run -s _list:check:*)", "fix:format": "npm run _check:format -- --write", "fix": "npm run seq -- $(npm -s run _list:fix:*)", + "precheck:links": "npm run build", "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ", "test": "npm run check", "update:pkgs": "npx npm-check-updates -u", diff --git a/static/refcache.json b/static/refcache.json new file mode 100644 index 0000000..1a96d40 --- /dev/null +++ b/static/refcache.json @@ -0,0 +1,630 @@ +{ + "https://analytics.google.com": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:43.150103-04:00" + }, + "https://blog.rook.io/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:43.211822-04:00" + }, + "https://cloud-native.slack.com": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:42.798322-04:00" + }, + "https://cloud-native.slack.com/archives/C057F81GFUG": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:43.065916-04:00" + }, + "https://cncf-techdocs.netlify.app/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.431682-04:00" + }, + "https://cncf-techdocs.netlify.app/404.html/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.427726-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.330152-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analysis/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.41211-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analysis/criteria/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.22135-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analysis/howto/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.303713-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analysis/templates/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.412104-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analysis/templates/analysis/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.332743-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analysis/templates/implementation/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.415932-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analysis/templates/issue/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.335492-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analysis/templates/issues-list/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.396202-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/analytics/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.338019-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/assistance/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.314312-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/hugo-and-docsy/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.327468-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/localization/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.379686-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/localization/ja/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.38741-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/netlify-domains-setup/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.311731-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/repo-setup/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.326156-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/sandbox-doc-primer/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.499941-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/searching-documentation/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.231922-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/services/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.337983-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/tags/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.400262-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/tags/project/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.507721-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/versioning-documentation/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.391897-04:00" + }, + "https://cncf-techdocs.netlify.app/docs/website-guidelines-checklist/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.404818-04:00" + }, + "https://creativecommons.org/licenses/by/4.0/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.210818-04:00" + }, + "https://developer.mozilla.org/en-US/docs/Web/Accessibility": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.847102-04:00" + }, + "https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.5755-04:00" + }, + "https://developers.google.com": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:40.68391-04:00" + }, + "https://developers.google.com/analytics/devguides/collection/gtagjs/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:45.186799-04:00" + }, + "https://developers.google.com/analytics/devguides/migration": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:40.365597-04:00" + }, + "https://developers.google.com/analytics/devguides/migration/measurement/add-ga4": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:41.008153-04:00" + }, + "https://developers.google.com/custom-search/docs/overview": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:38.568984-04:00" + }, + "https://developers.google.com/tech-writing": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:41.235297-04:00" + }, + "https://discourse.gohugo.io/t/audit-your-published-site-for-problems/35184": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:38.673658-04:00" + }, + "https://docs.github.com/en/get-started": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.550448-04:00" + }, + "https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.974872-04:00" + }, + "https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:40.556759-04:00" + }, + "https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:43.824829-04:00" + }, + "https://docs.netlify.com/domains-https/custom-domains/multiple-domains/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.56912-04:00" + }, + "https://docs.netlify.com/domains-https/netlify-dns/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.528687-04:00" + }, + "https://docsearch.algolia.com/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.903227-04:00" + }, + "https://docsfordevelopers.com/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:41.327555-04:00" + }, + "https://docusaurus.io/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:44.454182-04:00" + }, + "https://expertsupport.com/library/quick-and-easy-document-specifications/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:39.609931-04:00" + }, + "https://falco.org/docs/getting-started/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.973046-04:00" + }, + "https://git-scm.com/book/en/v2/Git-Tools-Submodules": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.523542-04:00" + }, + "https://github.com/Okabe-Junya": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.433444-04:00" + }, + "https://github.com/apps/dco": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.188531-04:00" + }, + "https://github.com/brianpursley": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.819634-04:00" + }, + "https://github.com/caniszczyk": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.673482-04:00" + }, + "https://github.com/carlisia": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.066678-04:00" + }, + "https://github.com/celestehorgan": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:43.110802-04:00" + }, + "https://github.com/chalin": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.933773-04:00" + }, + "https://github.com/cncf/foundation/blob/main/website-guidelines.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.855574-04:00" + }, + "https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.789697-04:00" + }, + "https://github.com/cncf/foundation/blob/master/code-of-conduct.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.580775-04:00" + }, + "https://github.com/cncf/foundation/blob/master/copyright-notices.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.954463-04:00" + }, + "https://github.com/cncf/glossary": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.470017-04:00" + }, + "https://github.com/cncf/project-template": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.95612-04:00" + }, + "https://github.com/cncf/tag-app-delivery": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.942477-04:00" + }, + "https://github.com/cncf/tag-env-sustainability": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.676592-04:00" + }, + "https://github.com/cncf/tag-runtime": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.337715-04:00" + }, + "https://github.com/cncf/techdocs": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.275112-04:00" + }, + "https://github.com/cncf/techdocs/blob/main/README.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.693644-04:00" + }, + "https://github.com/cncf/techdocs/issues": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.599716-04:00" + }, + "https://github.com/cncf/techdocs/issues/108": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.252231-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/analyses": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.795255-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.864864-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/README.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.922953-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analysis/README.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.974284-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analysis/criteria.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:43.815453-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analysis/howto.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.024236-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analysis/templates/README.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.741629-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analysis/templates/analysis.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.39977-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analysis/templates/implementation.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.456702-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analysis/templates/issue.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.436841-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analysis/templates/issues-list.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.988671-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/analytics.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:45.656684-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/assistance.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.893706-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/hugo-and-docsy.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.50712-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/localization/README.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.987962-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/localization/ja/README.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:44.349096-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/netlify-domains-setup.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:43.133184-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/repo-setup.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.933772-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/sandbox-doc-primer.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.2199-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/searching-documentation.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.23122-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/services.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.891135-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/versioning-documentation.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:44.813994-04:00" + }, + "https://github.com/cncf/techdocs/tree/main/docs/website-guidelines-checklist.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.016034-04:00" + }, + "https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.885666-04:00" + }, + "https://github.com/envoyproxy/envoy/blob/main/GOVERNANCE.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.779403-04:00" + }, + "https://github.com/etcd-io/website/pull/403": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.702767-04:00" + }, + "https://github.com/helm/community": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.421105-04:00" + }, + "https://github.com/hhiroshell": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.164426-04:00" + }, + "https://github.com/jonasrosland": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.826771-04:00" + }, + "https://github.com/kaitoii11": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.0703-04:00" + }, + "https://github.com/kenta-iijima": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.574544-04:00" + }, + "https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:43.580609-04:00" + }, + "https://github.com/kubernetes/website/blob/7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:44.346332-04:00" + }, + "https://github.com/kubernetes/website/blob/main/hugo.toml": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.655723-04:00" + }, + "https://github.com/kubernetes/website/blob/main/layouts/partials/navbar-version-selector.html": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.193851-04:00" + }, + "https://github.com/longhorn/website": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.512339-04:00" + }, + "https://github.com/naonishijima": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.75709-04:00" + }, + "https://github.com/nate-double-u": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.185856-04:00" + }, + "https://github.com/nate-double-u/technical-documentation-versioning": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.615197-04:00" + }, + "https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.966203-04:00" + }, + "https://github.com/nrb": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.535931-04:00" + }, + "https://github.com/opentracing/opentracing.io/issues": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.018763-04:00" + }, + "https://github.com/sftim": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:43.805308-04:00" + }, + "https://github.com/tbatard": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.80753-04:00" + }, + "https://github.com/thisisobate": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.199875-04:00" + }, + "https://github.com/vitessio/website/pull/1119": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.751462-04:00" + }, + "https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.43175-04:00" + }, + "https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.206262-04:00" + }, + "https://goharbor.io/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.657248-04:00" + }, + "https://helm.sh/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.065332-04:00" + }, + "https://inclusivenaming.org": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.397055-04:00" + }, + "https://kubernetes.io": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:43.368612-04:00" + }, + "https://kubernetes.io/docs/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.362238-04:00" + }, + "https://kubernetes.io/ja/docs/contribute/localization/#style-guide": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.933919-04:00" + }, + "https://lunrjs.com/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.138198-04:00" + }, + "https://prometheus.io/community/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.51314-04:00" + }, + "https://prometheus.io/docs": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.57018-04:00" + }, + "https://servicedesk.cncf.io": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:40.355292-04:00" + }, + "https://servicedesk.cncf.io/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:39.39085-04:00" + }, + "https://slack.cncf.io": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:43.836734-04:00" + }, + "https://support.google.com/analytics/answer/10089681": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:39.160574-04:00" + }, + "https://support.google.com/analytics/answer/10220869": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:43.011475-04:00" + }, + "https://support.google.com/analytics/answer/10268458": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:42.671721-04:00" + }, + "https://support.google.com/analytics/answer/10759417": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:41.212361-04:00" + }, + "https://support.google.com/analytics/answer/11583528": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:38.647647-04:00" + }, + "https://support.google.com/analytics/answer/9973999": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:44.228594-04:00" + }, + "https://support.linuxfoundation.org/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:42.307171-04:00" + }, + "https://technical-documentation-versioning.netlify.app/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.032013-04:00" + }, + "https://thanos.io/tip/contributing/how-to-contribute-to-docs.md": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:40.391896-04:00" + }, + "https://tockify.com/cncf.public.events/monthly": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:39.549384-04:00" + }, + "https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:39.488425-04:00" + }, + "https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:39.399607-04:00" + }, + "https://velero.io/": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.584554-04:00" + }, + "https://www.apache.org/licenses/LICENSE-2.0": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.424491-04:00" + }, + "https://www.cncf.io/project-metrics": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:38.392657-04:00" + }, + "https://www.cncf.io/wp-content/themes/cncf-twenty-two/images/favicon.ico": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.164465-04:00" + }, + "https://www.docsy.dev": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.471331-04:00" + }, + "https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.700718-04:00" + }, + "https://www.fluentd.org/testimonials": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:42.498739-04:00" + }, + "https://www.git-scm.com/book/en/v2/Git-Tools-Submodules": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:41.942795-04:00" + }, + "https://www.linuxfoundation.org/legal/privacy-policy": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:38.777636-04:00" + }, + "https://www.linuxfoundation.org/legal/trademark-usage": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:39.262344-04:00" + }, + "https://www.linuxfoundation.org/trademark-usage/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:40.189267-04:00" + }, + "https://www.lios.ca/en/blogue/concept-task-reference/": { + "StatusCode": 200, + "LastSeen": "2025-03-19T11:52:39.320251-04:00" + }, + "https://www.rfc-editor.org/rfc/rfc2119": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:38.675317-04:00" + }, + "https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872": { + "StatusCode": 206, + "LastSeen": "2025-03-19T11:52:39.706039-04:00" + } +} From 4dc892b17925b4ec937a60550a681a788f513448 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Tue, 8 Apr 2025 08:21:31 -0700 Subject: [PATCH 012/104] Add Vitess analysis document (#284) * Add Vitess analysis document. Signed-off-by: Dave Welsch * renaming file Signed-off-by: Nate W * fixing formatting issues Signed-off-by: Nate W * fixing formatting issues Signed-off-by: Nate W * Update per review comments, including recommendations for FAQ and troubleshooting. Signed-off-by: Dave Welsch * Update analyses/0014-vitess/analysis.md Co-authored-by: Patrice Chalin Signed-off-by: Nate W * Update analyses/0014-vitess/analysis.md Co-authored-by: Patrice Chalin Signed-off-by: Nate W * removing SEO, Analytics and local search sections as out of scope for this analyis. Signed-off-by: Nate W * updating spelling wordlist Signed-off-by: Nate W * fixing format Signed-off-by: Nate W * removing markdown disable no-bare-urls Signed-off-by: Nate W * updating codefence formatting Signed-off-by: Nate W * disabling fence-code-langage check on quoted content Signed-off-by: Nate W * fixing formatting Signed-off-by: Nate W --------- Signed-off-by: Dave Welsch Signed-off-by: Nate W Co-authored-by: Nate W Co-authored-by: Patrice Chalin Signed-off-by: Bruce Hamilton --- analyses/0014-vitess/analysis.md | 1055 ++++++++++++++++++++++++++++++ 1 file changed, 1055 insertions(+) create mode 100644 analyses/0014-vitess/analysis.md diff --git a/analyses/0014-vitess/analysis.md b/analyses/0014-vitess/analysis.md new file mode 100644 index 0000000..6f622b4 --- /dev/null +++ b/analyses/0014-vitess/analysis.md @@ -0,0 +1,1055 @@ +--- +title: Vitess Documentation Analysis +tags: Vitess +created: 2025-02-19 +modified: 2025-02-19 +author: Dave Welsch (dwelsch-esi) +# prettier-ignore +cSpell:ignore: Welsch dwelsch vitess topo pasteable mysqlshell vtctldclient lede +--- + + + +## Introduction + +This document analyzes the effectiveness and completeness of the +[Vitess][project-website] open source software (OSS) project's documentation and +website. It is funded by the CNCF Foundation as part of its overall effort to +incubate, grow, and graduate open source cloud native software projects. + +According to CNCF best practices guidelines, effective documentation is a +prerequisite for program graduation. The documentation analysis is the first +step of a CNCF process aimed at assisting projects with their documentation +efforts. + +### Purpose + +This document was written to analyze the current state of Vitess documentation. +It aims to provide project leaders with an informed understanding of potential +problems in current project documentation. A second [implementation] document +outlines an actionable plan for improvement. A third document is a [list of +issues][issues list] to be added to the project documentation repository. These +issues can be taken up by contributors to improve the documentation. + +This document: + +- Analyzes the current Vitess technical documentation and website +- Compares existing documentation against the CNCF’s standards +- Recommends a program of key improvements with the largest return on investment + +### Scope of analysis + +The documentation discussed here includes the entire contents of the website, +the technical documentation, and documentation for contributors and users on the +Vitess GitHub repository. + +The Vitess website and documentation are written in Markdown and are compiled +using the Hugo static site generator with the [Bulma] CSS framework and +apparently served from Netlify. The site does not appear to use a theme, or uses +a default theme (there is no theme given in the configuration file.) The site's +code is stored in its own repository in the Vitess GitHub project. + +#### In scope + +- Website: +- Documentation: +- Website repo: +- Project repo (for reference): + +#### Out of scope + +- Other Vitess repos: (In general, other Vitess + code repos are out of scope) + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** concerns documentation for users of the Vitess + software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Vitess OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability + +Each section begins with summary ratings based on a rubric with appropriate +[criteria] for the section, then proceeds to: + +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help Vitess users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [implementation] document breaks the recommendations down into +concrete actions that can be implemented by project contributors. Its focus is +on drilling down to specific, achievable work that can be completed in +constrained blocks of time. Ultimately, the implementation items are decomposed +into a series of [issues] and entered as GitHub issues in the website +[repository][project-doc-website]. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the **[implementation] plan** and **[issues list]**. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation](#project-documentation) +- [Contributor documentation](#contributor-documentation) +- [Website and documentation infrastructure](#website-and-infrastructure) + +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria] specification. + +#### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards, +and suggests possible improvements. In most cases there is more than one way to +do things. Few recommendations here are meant to be prescriptive. Rather, the +recommended implementations represent the reviewers' experience with how to +apply documentation best practices. In other words, borrowing terminology from +the lexicon of [RFCs][rfc-spec], the changes described here should be understood +as "recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. + +## Project documentation + +Vitess is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| Criterion | [Rating (1-5)] | +| -------------------------- | ----------------------------- | +| Information architecture | 2. Needs improvement | +| New user content | 2. Needs improvement | +| Content maintainability | 4. Meets or exceeds standards | +| Content creation processes | 1. Not present | +| Inclusive language | 2. Needs improvement | + +### Comments + +The following sections contain brief assessments of each element of the Project +Documentation rubric. + +#### Information architecture + +**Conceptual content**: Is there high level conceptual (“About”) content? + +Yes, the site contains conceptual material explaining what Vitess is and how it +works, in both the [Overview](https://vitess.io/docs/21.0/overview/) and +[Concepts](https://vitess.io/docs/21.0/concepts/) sections. + +The introduction to the Overview could be more helpful to new users. + +There is an extensive FAQ that contains much information of all types, but +especially conceptual information. The overview introduction in the FAQ is +actually more descriptive and succinct than the one on the main web page: + +> Vitess is a database solution for deploying, scaling and managing large +> clusters of database instances. + +The FAQ is outside the versioned documentation. + +**Feature complete**: Is the documentation feature complete? (i.e., each product +feature is documented)? + +Yes, the documentation seems to cover all features of Vitess (as far as I can +tell). However, see the following regarding task instructions. + +**Task instructions**: Are there step-by-step instructions (tasks, tutorials) +documented for features? + +Yes, there are task instructions covering all major classes of tasks required to +use Vitess: + +- [Installation](https://vitess.io/docs/21.0/get-started/) +- Setup and use +- Administration + +Except for Installation, all task documentation is in one of two places: + +- The [User Guides](https://vitess.io/docs/21.0/user-guides/). +- An extensive FAQ that contains task instructions. + +Despite being labeled "Task-based guides," the task instructions in the User +Guide are written from a feature-oriented perspective, which lessens the +documentation's efficiency. + +**No features missing tasks**: Is the documentation free of any key features +which are documented but missing task documentation? + +It looks like there are features that don't have adequate task descriptions. +Features are represented, but often the task descriptions are not written as +procedures. For examples, see +[Information architecture](#information-architecture-1) in +[Recommendations](#recommendations). + +**Happy path**: Is the “happy path”/most common use case documented? + +Vitess is a complex system with many configuration options. That said, I believe +that setting up and running a production server in Kubernetes is the main use +case, and is covered. + +**Isolated, atomic tasks**: Does task and tutorial content demonstrate atomicity +and isolation of concerns? (Are tasks clearly named according to user goals?) + +No, tasks are not isolated. The User Guide has the following issues: + +- Tasks are intermingled with discussion of the features +- Multiple tasks are presented per page +- Task names are often not present in table of contents (TOC) headings +- Where present, task names are ambiguous or misleading + +Titles of pages and sections are often feature-based, making it hard to find +procedures to complete tasks. + +**Escalation path**: If the documentation does not suffice, is there a clear +escalation path for users needing more help? (FAQ, Troubleshooting) + +No clear escalation path exists. There are Troubleshooting guides in the +following sections: + +- Running in Production +- Advanced > Distributed Atomic Transactions +- Migration + +There is a troubleshooting section outside the versioned documentation. + +There is a lengthy troubleshooting section in the FAQ. + +There is a separate special-purpose FAQ, for VReplication, in the Reference. + +There is no glossary. + +There is a Vitess Community page on the product website. This is accessible from +the documentation as well. It has headings for Contributing, Monthly Meetings, +Governance, Code of Conduct, etc. It lists channels (Slack, Stack Overflow, +Issue tracker) but does not prominently feature a “Support” or “Getting Help” +heading. + +**Complete API reference**: If the product exposes an API, is there a complete +reference? + +Not applicable. Vitess does not have an exposed API. + +However, Vitess does have several command-line interface to servers and +utilities, and these are documented in the Reference. + +**Accurate and up-to-date**: Is content up to date and accurate? + +Yes, documentation is versioned and prominently includes the latest Stable and +Development versions. + +However, there are several important sections that are maintained outside the +versioned documentation: + +- Troubleshooting +- FAQ +- Information about the release procedure + +#### New user content + +**Getting started entry**: Is “getting started” clearly labeled? (“Getting +started”, “Installation”, “First steps”, etc.) + +Yes, the Get Started section contains instructions to install, set up, and run +Vitess in four different environments (OSes and container solutions). + +The Get Started guide has better written instructions than the User Guide, but +procedures could still be clearer. There is no meta-text explaining when you +would want to use each install option (the test installs are based on platform, +but a discussion of development, test, and production environments would still +help). + +**Installation**: Is installation documented step-by-step? + +No, instructions are not documented step-by-step, strictly speaking. +Instructions are generally sequential down the page but not numbered. As with +the User Guide procedures, steps could be rewritten so that they're more +explicit. + +**Multiple OS**: If needed, are multiple OSes documented? + +Yes, multiple OSes (and container platforms) are documented. Instructions are +given for a Kubernetes (production) install, and three local installs: Linux, +Mac, and Docker. The local (non-Kubernetes) installs are "for test purposes," +but no further details are provided. The default local install for pre-compiled +binaries does not explicitly list what OSes are supported. + +**Getting started next steps**: Do users know where to go after reading the +getting started guide? + +Yes, there is a Next Steps section at the end of each install except the Docker +local install. However, the Next Steps section is perfunctory, pointing in all +cases to the Move Tables page in the Migration guide. + +**New user signpost**: Is your new user content clearly signposted on your +site’s homepage or at the top of your information architecture? + +No, there is no clear entry path for new users. They'll probably make their way +through the install and then try to figure out how to implement their migration +case (which probably fits one of the documented scenarios, but there is no clear +way for them to find it). + +**Sample code**: Is there easily copy-pasteable sample code or other example +content? + +Yes, command-line examples are plentiful. There is no click-to-copy, however. +Users must highlight and copy manually. + +#### Content maintainability & site mechanics + +**Searchability**: Is your documentation searchable? + +Yes, there is a text Search feature that is limited to the currently displayed +version. It seems to work very well. + +Search is full-text, so common search terms can result in an unwieldy number of +results. + +**Localization & i18n directories**: Are you planning for +localization/internationalization with regard to site directory structure? + +Yes, there are full versions of the documentation in both English and Chinese. + +The Chinese versions are reportedly not up to date with the latest software +version. + +**Localization framework**: Is a localization framework present? + +Yes, there seems to be some infrastructure for multiple languages. I'm not sure +how translation is done in Hugo. + +**Versioning**: Do you have a clearly documented method for versioning your +content? + +Yes, releasing a new version is scripted. The repository contains instructions. +The latest three released versions are available on the website. + +#### Content creation processes + +**Content creation process**: Is there a clearly documented (ongoing) +contribution process for documentation? + +There are instructions for building and releasing the documentation, as well as +detailed instructions for contributing instructional videos. However, there are +no instructions for contributing technical documentation or fixing documentation +issues. + +Presumably a contributor can submit a pull request on the website repo to amend +or add to the documentation, but there is no procedure documented. There is a +notice that no grammar or typo fixes are accepted from accounts less than a year +old. + +**Release process**: Does your code release process account for documentation +creation & updates? + +No, neither the [Contribute](https://vitess.io/docs/contributing/) documentation +nor the +[CONTRIBUTING.md](https://github.com/vitessio/vitess/blob/main/CONTRIBUTING.md) +file in the product repo describes how to contribute documentation. There is no +Contribution section in the website repo. + +**Review and approval**: Who reviews and approves documentation pull requests? + +Unknown. The Governance document gives detailed descriptions of the User, +Contributor, and Maintainer roles. It does not mention documentation explicitly +except as one of the contributor tasks. + +**Site owner and maintainer**: Does the website have a clear owner/maintainer? + +No, the main project repo lists maintainers, along with areas of expertise. None +of them lists documentation as an area of expertise. There is no owner +information on the website repo. + +#### Inclusive language + +**Non-inclusive phrases**: Are customer-facing utilities, endpoints, class +names, or feature names free of non-recommended words as documented by the +[Inclusive Naming Initiative](https://inclusivenaming.org) website? + +Not entirely, but there have clearly been attempts to correct non-inclusive +language on the site. For example, “primary” replaces “master” to describe the +database of record in the Vitess product. Some non-inclusive language remains. +Examples: “sanity check”; “master database” (these can be found using the +website's Search function). + +Of course, some of this language exists in product command elements and outputs +that cannot be changed in the documentation without first eliminating them in +code (command line options, for example). + +**Ableist language**: "Is the project free of language like 'simple', 'easy', +etc.?" + +No. A few examples exist. These should be evaluated and replaced on a case by +case basis. + +### Recommendations + +#### Information architecture + +##### Get Started + +Write an introduction on the +[Get Started](https://vitess.io/docs/21.0/get-started/) landing page. This +introduction should outline a path for new users something like the following: + +1. Install test environment +2. Configure test environment +3. Test Vitess + +After this familiarization process, there should be a a pointer to a User Guide +processes that walk the reader through the product's "happy path" in a more or +less linear path (a series of tasks). That might look something like this: + +1. Plan production installation +2. Install production version +3. Configure production environment +4. Populate databases +5. Run queries +6. Maintain and add cells/shards/databases. + +The "Next steps" sections on the test installation pages should point readers to +new-user configuration and testing procedures. + +The "Next steps" section on the production installation page should point users +to whatever is next in the User Guide documentation. This can be more than one +path. Make it conditional based on the task a reader might want to accomplish +after installation: Test the installation? Plan a cluster? Something else? + +##### Conceptual Info + +Clarify the beginning of the +[Overview](https://vitess.io/docs/21.0/overview/whatisvitess/) ("What is ...") +The introduction from the README in the [code repository][project-website] is +pretty good: + +> Vitess is a cloud-native horizontally-scalable distributed database system +> that is built around MySQL. + +Or the introduction that this replaced: + +> Vitess is a database clustering system for horizontal scaling of MySQL through +> generalized sharding. + +###### Tasks + +The User Guides page _says_ "Task-based guides for common usage scenarios". +That's the right idea, but implementation must be improved if readers are to +find and carry out the documented tasks. + +The User Guides require three types of changes to maximize their effectiveness: + +- Rename +- Rewrite +- Reorganize + +###### Rename + +Rename the individual pages in the User Guides to reflect the tasks that are +described there. Use verbs ending in "-ing" (along with a noun that describes +the object of the task, if applicable). This helps readers find the right +content in at least two ways: + +- Makes the TOC more coherent +- Gives meaningful results in the site-wide Search + +Here are three examples from the +[same page](https://vitess.io/docs/21.0/user-guides/configuration-basic/global-topo/) +(the content of these sections is not considered here): + +- _Choosing a TopoRoot_: A good title. Describes the task ("choosing") and the + object of the task ("TopoRoot"). +- _Moving to a different TopoServer_: A good title. Describes the task + ("moving"). Normally I'd recommend a more direct reference to the object -- + "Moving TopoServers" -- but in this case the phrase ".. to a different + TopoServer" removes ambiguity. +- _Backups_: Not a helpful title. It's not clear or what you're backing up or + what what aspect of the backups you're talking about. I'd change this to + "Backing up TopoServer data". + +Also on the Global TopoServer page, by the way: + + + +> The following command line options are required for every Vitess component: +> +> ``` +> --topo_implementation=etcd2 --topo_global_server_address= +> --topo_global_root=/vitess/global +> ``` +> +> To avoid repetition we will use in our examples to signify the +> above flags. + +Remove this. The `` placeholder does not seem to have been +implemented. There are no mentions of `` elsewhere in the +documentation, and in any case each would have to refer back to this page. + +In the FAQ: Rename the questions into concise headings when you consolidate the +FAQ into the versioned documentation (see _Reorganize_ below). + +###### Rewrite + +A reader typically consults the User Guide to find out how to do something. The +User Guides should consist primarily of procedures. + +There are some Vitess features for which the User Guide gives a description but +does not provide adequate instructions for their use. + +For example, look at +[Creating a Backup](https://vitess.io/docs/21.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup/) + +This page appears to be well named ("Creating a Backup" is a descriptive task +title) and properly placed (it resides in a logical location in the User Guide). +However, the page itself buries the lede (it doesn't provide the procedure until +far down the page): There is no actual command line given between +_Configuration_ and _Common Errors and Resolutions_ The "how to" procedure +should be prominently featured. + +Further down the page, another backup option, _Using mysqlshell_, has the same +shortcomings: No actual command is apparent. + +Instead, write these pages as step-by-step descriptions of how to perform a +task. Each step should be a concise instruction, with any required instruction +or text illustrated and explained (much of the time, this is a monospace +code/CLI block displaying the command-line instruction to use). This can be an +example, but only if it is obvious how the reader should use the command. Other +times, it means showing the required form of the command, with placeholders for +parameters, and explaining those parameters in the following text. + +The +[Creating a cell](https://vitess.io/docs/21.0/user-guides/configuration-basic/create-cell/) +page shows a CLI command: + +> ```bash +> vtctldclient AddCellInfo \ +> --root /vitess/cell1 \ +> --server-address \ +> cell1 +> ``` + +It's not clear if `/vitess/cell1` is a user-definable parameter or not. The +server address placeholder, ``, is not defined in the text. + +Here's how I'd rewrite it, defining placeholders for the parameters: + +> ```bash +> vtctldclient AddCellInfo \ +> --root \ +> --server-address \ +> cell1 +> ``` +> +> where: +> +> - is the root directory of the server installation +> - is the IP address of the topo server + +(or whatever the actual descriptions of the parameters are.) + +Here's an outline for a one-page procedure writeup: + +- Title ("ABCing XYZ") + - Context (Describe where the procedure fits in the overall use case) + - Prerequisites (Hardware and software requirements, dependencies, procedures + that must be completed first) + - Procedure ("To ABC an XYZ, do the following.") + - Step 1 (_One_ CLI command, or action. Don't combine actions.) + - Step 2 (etc.) + - Result (Optional - include only if there's something remarkable about the + outcome.) + - Next Steps (What procedure or use case typically follows this. If it depends + on context, explain the options.) + +###### Reorganize + +Ensure that the various sections of the User Guide cover all usage scenarios. +Reorganize the User Guide: + +First, organize by user role, if there are distinct roles. As I understand it, +there are basically three user roles in Vitess: + +- Vitess admin +- Database admin +- Application developer + +User roles traditionally are the basis for a "User Guide": + +- Admin Guide +- DBA Guide +- Programmer's Guide +- etc. + +Within roles, organize the tasks around use cases. Don't be afraid to split up +tasks that use the same tool (CLI or other). In other words, pick and choose +commands and actions that server a use case rather than trying to document +everything you can do with the command in one place. (There is a place to +exhaustively document a tool, but that's in the Reference, not a User Guide.) + +The existing Vitess User Guides are already partially organized around user +roles, but they can be regrouped. In any case, make the user roles explicit: + +_Vitess admin_: + +- Configuration +- Running in production +- Operational +- Migration + +_DBA_: + +- VSchema and Query Serving +- SQL statement analysis +- Making schema changes + +_Application programmer_: + +- Query serving +- Making schema changes (don't duplicate the section here. Instead provide links + to any tasks that are identical) +- Query optimization + +(Again, these are my understanding of the Vitess user roles. Adjust the details +if they're different.) + +Get rid of the FAQ. This FAQ has apparently grown from a repository for common +questions into a separate de facto technical documentation set. Move all of the +FAQ topics and information into the versioned documentation. + +Merge information with existing sections and/or move FAQ topics to the +documentation intact, as appropriate. For example, much of the FAQ amounts to a +good conceptual overview of the product; it should be part of the conceptual +overview. In its current form it is unversioned and hard to find. + +###### Troubleshooting + +Consolidate all troubleshooting information into a Troubleshooting Guide. Or, +create one troubleshooting guide per user guide/user role. In either case, +create an escalation path for any problems with a task (the escalation path +might be: _troubleshooting procedure > Slack Channel > project Issue_). Get rid +of the +[VReplication FAQ](https://vitess.io/docs/21.0/reference/vreplication/faq/) in +the reference section and put the information in a troubleshooting section. + +Locate the troubleshooting guide or guides within the versioned technical +documentation. Changes to the product affect troubleshooting procedures as well +as other types of information, and the documentation structure should reflect +that. + +###### Glossary + +Write a glossary. This is different from the "Concepts" page – the explanations +of terms is less in-depth. The glossary contains not just key terms but any word +or phrase that the reader might not know: abbreviations and acronyms, +definitions of Vitess-specific terms, and explanations of jargon used in Vitess +("topo", for example). + +###### Other recommendations + +Rename ["Reference > Programs"](https://vitess.io/docs/21.0/reference/programs/) +to "Command line reference" or "Tools reference". Consider splitting into two or +more sections by type of application: by function or user role. CLIs should be +labeled as such and separated from GUI tools. + +#### New user content + +Is there an alternative to Kubernetes for running in production? Explain. Give +an explicit list of supported OSes. This can be done by expanding the Get +Started landing page (see +[Information Architecture > Get Started](#information-architecture)). + +Rewrite installation instructions as step by step procedures. + +Expand the production install +[Next Step](https://vitess.io/docs/21.0/get-started/operator/#next-steps) +section to accommodate different configurations (conversion, green field, etc.). +Differentiate between Next Steps for test/development installations and +production installation. + +Put enough information on the Get Started landing page to orient new users as +described in +[Information Architecture > Get Started](#information-architecture). + +Rename sections so that it's easier to find the right page in Search: + +- Use "-ing" verbs for task pages as previously described +- Use the word "reference" in CLI references +- Use nouns for architectural components, features, and concepts + +#### Content maintainability & site mechanics + +No recommendations. Technical aspects of infrastructure and maintenance seem +excellent. + +#### Content creation processes + +There is no documentation for website and tech doc content creation. Such +documentation could include: + +- Instructions for documenting tasks associated with new features +- Instructions for fixing documentation issues +- Templates for task write-ups and command references +- Guidelines for amending conceptual information with new features +- A style manual +- A review and approval process, separate from the code process +- A link from the code contribution instructions to the doc instructions +- A maintainer designated to be responsible for website maintenance and for + documentation changes and updates +- Getting started instructions for new documentation contributors + +In practice, open source projects rarely contain all this information. At a +minimum, document the following processes for contributors: + +- Documenting a new release + - Generating, testing, and deploying the new release docs, including how to + publish release notes + - Demoting, archiving, or deleting down-level releases +- Creating a doc issue +- Fixing and closing a doc issue +- How to contact the website and documentation maintainer with questions +- Getting started instructions for new documentation contributors + +These processes should address documentation-specific concerns, not just parrot +the code release procedures (although there may be many of the same steps). + +#### Inclusive language + +Search the document for non-inclusive terms, especially tier-1 and tier-2 terms +per the [Inclusive Naming Initiative](https://inclusivenaming.org/). Replace +with recommended language where possible. + +## Contributor documentation + +Vitess is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | ----------------------------- | +| Communication methods documented | 3. Meets standards | +| Beginner friendly issue backlog | 2. Needs improvement | +| “New contributor” getting started content | 2. Needs improvement | +| Project governance documentation | 4. Meets or exceeds standards | + +### Comments + +The following sections contain brief assessments of each element of the +Contributor Documentation rubric. + +#### Communication methods documented + +**Text communication channel**: Is there a Slack/Discord/Discourse/etc. +community and is it prominently linked from your website? + +Yes, the community page lists a Slack channel. + +**Repository link**: Is there a direct link to your GitHub +organization/repository? + +Yes, the community page and the footer list the GitHub page for the product. + +**Project meetings**: Are weekly/monthly project meetings documented? Is it +clear how someone can join those meetings? + +Yes, the community page lists the monthly community meetings. + +**Mailing lists**: Are mailing lists documented? + +No, there does not appear to be an email list. + +#### Beginner friendly issue backlog + +**Issue triage**: Are docs issues well-triaged? + +No, there does not appear to be any mechanism for prioritizing issues in the +GitHub repo. + +**Good first issues**: Is there a clearly marked way for new contributors to +make code or documentation contributions (i.e. a “good first issue” label)? + +Yes, there is a “good first issue” label in the website repo issues list. + +**Issue documentation**: Are issues well-documented (i.e., more than just a +title)? + +Yes, issues seem to have at least a paragraph description. However, there is no +issues template or guidelines for documenting issues, so the quality of the +descriptions is inconsistent. + +**Issue freshness**: Are issues maintained for staleness? + +No, the oldest open issue is over 6 years old. + +#### New contributor getting started content + +**Community featured on website**: Do you have a community repository or section +on your website? + +Yes, there is a Community link in the site’s menu bar, leading to the Community +page. + +**New contributor document**: Is there a document specifically for new +contributors/your first contribution? + +No, I could not find a new contributor's document. + +**New user help**: Do new users know where to get help? + +There is no prominent document to guide new users. + +#### Project governance documentation + +**Governance documentation**: Is project governance clearly documented? + +Yes, there are Governance and Code of Conduct documents in the project repo. + +### Recommendations + +#### Communication methods documented + +No recommendations. + +#### Beginner friendly issue backlog + +Create an issue template to ensure that issue descriptions are consistent and +complete. + +Go through the issues backlog and close or update old issues. + +#### New contributor getting started content + +Write a "new contributors" document. Post prominently. + +#### Project governance documentation + +No recommendations. + +## Website and infrastructure + +Vitess is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | ----------------------------- | +| Single-source for all files | 5. Exemplary | +| Meets min website req. (for maturity level) | 2. Needs improvement | +| Usability, accessibility, and design | 3. Meets standards | +| Branding and design | 4. Meets or exceeds standards | +| Case studies/social proof | 2. Needs improvement | +| SEO, Analytics, and site-local search | out of scope | +| Maintenance planning | 2. Needs improvement | +| HTTPS access & HTTP redirect | 5. Exemplary | + +### Comments + +The following sections contain brief assessments of each element of the Website +and documentation infrastructure rubric. + +#### Single source + +**Single source for docs**: Does the project have a single source for +documentation? If not, is there a reason? + +Yes, the website and tech doc content are all in one GitHub repo. + +#### Minimal website requirements + +**Website guidelines**: Are all guidelines satisfied? + +Yes, the website mostly meets all criteria for a CNCF graduated website, +including hosting, copyright, CNCF branding, and trademark. + +**Docs analysis**: Are all follow-up actions addressed? + +Pending: There is no reason to believe the Vitess team won’t follow through on +recommendations in this analysis. + +**Project doc: stakeholders**: Are all stakeholder needs identified? + +No, roles are not explicitly defined in the documentation. There is some +differentiation among roles implicit in the docs (admin permissions, RBAC +support, etc.), but it is not used to organize the content. + +**Project doc: hosting**: Hosted directly. + +Yes, the site is hosted on Netlify. + +**Project doc: user docs**: Fully addresses needs of key stakeholders? + +Yes, the documentation probably addresses all stakeholder needs, but is not +organized so that users can find the docs efficiently. + +#### Usability, accessibility and devices + +**Mobile**: Is the website usable from mobile? + +Yes, the site seems to adapt well to small screen use. + +**Readability**: Are doc pages readable? + +Yes, documentation pages are readable on all tested platforms and screen sizes. + +**Mobile navigability**: Are all / most website features accessible from mobile +-- such as the top-nav, site search and in-page table of contents? + +Most website features are accessible from mobile. + +**Mobile-first design**: Might a [mobile-first] design make sense for your +project? + +No, this project might occasionally be accessed on mobile but it doesn't seem +likely to be the main use case. + +**Color contrast**: Are color contrasts significant enough for color-impaired +readers? + +Yes, text is black on white. Font is a very legible sans serif. + +**Keyboard-only**: Are most website features usable using a keyboard only? + +Yes, most features are usable. However, tab navigation is awkward and +time-consuming. + +**Text-to-speech**: Does text-to-speech offer listeners a good experience? + +Text-to-speech was not tested. + +#### Branding and design + +**Recognizable brand**: Is there an easily recognizable brand for the project +(logo + color scheme) clearly identifiable? + +Yes, the site has a consistent design. The orange “layered sheets” logo is +recognizable. + +**Consistent branding**: Is the brand used across the website consistently? + +Yes, branding is used consistently. + +**Typography**: Is the website’s typography clean and well-suited for reading? + +Yes, the font is a little small in places, but overall legible. Font scales +gracefully when magnified in the browser. + +#### Case studies & social proof + +**Case studies**: Are there case studies available for the project and are they +documented on the website? + +No, I did not see any case studies. Some of the many videos might contain case +studies, though. + +**Testimonials**: Are there user testimonials available? + +No, there do not seem to be testimonials available on the site. The logo wall +does not have live links. + +**Active blog**: Is there an active project blog? + +Yes, there is a blog. The last entry was two months ago, but it seems to be +updated semi-regularly. + +**Community talks listed**: Are there community talks for the project and are +they present on the website? + +Yes, there are many videos on the “Learning Resources” page, containing a +variety of topics including community talks. + +**Logo wall**: Is there a logo wall of users/participating organizations? + +Yes, there is a substantial logo wall on the product landing page. + +#### Maintenance planning + +**Well supported website tooling**: Is your website tooling well supported by +the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF +projects (our recommended tech stack?) + +Yes, the site is implemented using Hugo, CNCF's recommended site generator, and +hosted on Netlify. + +**Cultivating website maintainers**: Are you actively cultivating website +maintainers from within the community? + +Unknown. There is no documented evidence of recruitment on the website or in the +repository. + +**Site build times**: Are site build times reasonable? + +I did not try building the site but have no reason to believe that the build +time is excessive. + +**Maintainer permissions**: Do site maintainers have adequate permissions? + +Unknown. + +#### Other + +**HTTPS**: Is your website accessible via HTTPS? + +Yes, all site pages use HTTPS. + +**HTTP redirect**: Does HTTP access, if any, redirect to HTTPS? + +Yes, pages requested using HTTP are redirected to existing HTTPS pages +seamlessly. + +### Recommendations + +#### Single-source requirement + +No recommendations. + +#### Minimal website requirements + +Identify stakeholder and user roles. Organize task documentation around user +roles (see [Information architecture](#information-architecture)). + +#### Usability, accessibility and devices + +No recommendations. + +#### Branding and design + +No recommendations. + +#### Case studies/social proof + +Include case studies and testimonials on the product website. If these are +already among the video content, tag them and feature them on the landing page. + +Update blog content at least monthly. + +#### Maintenance planning + +TBD + +#### Other + +No recommendations. + +## References and notes + +### Rating values + +The numeric rating values used in this document are as follows: + +1. Not present +2. Needs improvement +3. Meets standards +4. Meets or exceeds standards +5. Exemplary + +### References + +[criteria]: ../../docs/analysis/criteria.md +[implementation]: ./implementation.md?no-link-check +[issues list]: ./issues-list.md?no-link-check +[project-doc-website]: https://vitess.io/docs/ +[project-website]: https://vitess.io/ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[Bulma]: https://bulma.io/ From 214fa5cf4da34c587f3943cb6405626c5c816921 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 24 Apr 2025 06:04:10 -0400 Subject: [PATCH 013/104] Analytics docs rework: factor out UA-to-GA4 instructions, and more (#312) Signed-off-by: Bruce Hamilton --- .htmltest.yml | 1 + docs/analytics/README.md | 23 +++++++++++++++ docs/{analytics.md => analytics/ua-to-ga4.md} | 28 ++++++------------- docusaurus.config.ts | 10 +++++-- netlify.toml | 6 ++++ package.json | 5 +++- static/refcache.json | 8 ++++++ 7 files changed, 58 insertions(+), 23 deletions(-) create mode 100644 docs/analytics/README.md rename docs/{analytics.md => analytics/ua-to-ga4.md} (92%) create mode 100644 netlify.toml diff --git a/.htmltest.yml b/.htmltest.yml index 8594ce7..84e17fd 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -5,6 +5,7 @@ TestFilesConcurrently: true IgnoreDirs: IgnoreInternalURLs: # list of paths IgnoreURLs: # list of regexes of URLs or path to be ignored + - ^https?://localhost - \?no-link-check # FIXME: temporary ignore rules - assistance\.md diff --git a/docs/analytics/README.md b/docs/analytics/README.md new file mode 100644 index 0000000..cc198c7 --- /dev/null +++ b/docs/analytics/README.md @@ -0,0 +1,23 @@ +# Analytics + +## Google Analytics + +- [CNCF sandbox][] projects currently onboarding, should open a [Service Desk][] + ticket to either: + - Request a transfer of their existing GA properties to the **CNCF Projects** + Google Analytics account. The first step is to make projects@cncf.io and + Administrator of their existing GA account. + - Request the creation of a new analytics property. +- For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your + [Docsy][]-based website, see [Adding Analytics][]. + +> **Archived instructions**: for details on how to migrate from Universal +> Analytics to GA4, see +> [Migrating Universal to Google Analytics 4](ua-to-ga4.md). + +[adding analytics]: + https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics +[CNCF sandbox]: https://github.com/cncf/sandbox +[docsy]: https://www.docsy.dev +[ga4]: https://support.google.com/analytics/answer/10089681 +[service desk]: https://github.com/cncf/servicedesk diff --git a/docs/analytics.md b/docs/analytics/ua-to-ga4.md similarity index 92% rename from docs/analytics.md rename to docs/analytics/ua-to-ga4.md index 6ece103..79733ef 100644 --- a/docs/analytics.md +++ b/docs/analytics/ua-to-ga4.md @@ -2,23 +2,13 @@ cSpell:ignore: gtag kubernetes --- -# Analytics +# Migrating Universal to Google Analytics 4 -This page describes how to setup or upgrade Google Analytics (GA) for your CNCF -project's website. +This page describes how to migrate your CNCF project from Google's [Universal +Analytics][ua] (UA) to [Google Analytics 4][ga4] (GA4). -> **Deprecation notice**: Google's [Universal Analytics will be going away][ua] -> in 2023. - -When adding analytics to a new CNCF project website, use [Google Analytics -4][ga4] (GA4). - -## Adding Google Analytics - -For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your -[Docsy][]-based website, see [Adding Analytics][]. - -## Migrating to Google Analytics 4 +> **Deprecation notice**: Google started deprecating UA in 2023. As of 2024, UA +> is no longer supported, and UA data is no longer accessible. There are many ways to upgrade your project to [GA4][]. We describe one such process below. Adapt it to your needs. Useful resources to consider include: @@ -30,7 +20,7 @@ process below. Adapt it to your needs. Useful resources to consider include: - **Help center** resource: [Migrate from Universal Analytics to Google Analytics 4][migration-help] -### Stage 0 - preparation +## Stage 0 - preparation In preparation for the migration, follow these steps: @@ -51,7 +41,7 @@ In preparation for the migration, follow these steps: - Take note of which library or libraries (some sites use both) your site is using. -### Stage 1 - create a GA4 site tag +## Stage 1 - create a GA4 site tag Objectives: @@ -138,7 +128,7 @@ 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. -### Stage 2 - configure the GA4 ID as the main analytics ID +## 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][] analytics library. @@ -174,7 +164,7 @@ analytics library. partial. In this case, make use of the GA4 measurement ID in your partial or site config file, as appropriate. -### Stage 3 - switch to native support for GA +## Stage 3 - switch to native support for GA In cases where your project website (temporarily) used some custom layouts or code (such as custom Hugo partials) to enable GA4, consider removing the custom diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 96b5c27..2cb5443 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -7,14 +7,18 @@ import type * as Preset from '@docusaurus/preset-classic'; const title = 'CNCF TechDocs'; const repo = 'https://github.com/cncf/techdocs'; +const buildEnv = process.env.BUILD_ENV || 'production'; +const isProd = buildEnv === 'production'; + const config: Config = { title, // tagline: '', favicon: 'https://www.cncf.io/wp-content/themes/cncf-twenty-two/images/favicon.ico', // TODO: localize? - // Production URL: - url: 'https://cncf-techdocs.netlify.app/', // FIXME if/once we get a domain + url: isProd + ? 'https://cncf-techdocs.netlify.app' + : process.env.DEPLOY_PRIME_URL || 'http://localhost:3000', baseUrl: '/', // GitHub pages deployment config. TODO: this still useful? @@ -37,7 +41,7 @@ const config: Config = { { docs: { sidebarPath: './sidebars.ts', - editUrl: `${repo}/tree/main`, + editUrl: isProd ? `${repo}/tree/main` : undefined, }, theme: { customCss: './src/css/custom.css', diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 0000000..cbdbceb --- /dev/null +++ b/netlify.toml @@ -0,0 +1,6 @@ +[build] +publish = "build" +command = "npm run build:preview" + +[context.production] +command = "npm run build:production" diff --git a/package.json b/package.json index cf6d672..3fc71a6 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "version": "0.0.0", "description": "Resources provided by the CNCF Technical Documentation team.", "scripts": { + "_build": "docusaurus build", "_check:format:any": "npx prettier --check --ignore-path ''", "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)", "_check:format": "npx prettier --check .", @@ -29,7 +30,9 @@ "update:pkgs": "npx npm-check-updates -u", "docusaurus": "docusaurus", "start": "docusaurus start", - "build": "docusaurus build", + "build:preview": "npm run _build", + "build:production": "npm run _build", + "build": "BUILD_ENV=dev npm run _build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", diff --git a/static/refcache.json b/static/refcache.json index 1a96d40..1b5b4d9 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -255,6 +255,14 @@ "StatusCode": 206, "LastSeen": "2025-03-19T11:52:38.95612-04:00" }, + "https://github.com/cncf/sandbox": { + "StatusCode": 206, + "LastSeen": "2025-04-22T19:39:31.8704-04:00" + }, + "https://github.com/cncf/servicedesk": { + "StatusCode": 206, + "LastSeen": "2025-04-22T19:39:32.21738-04:00" + }, "https://github.com/cncf/tag-app-delivery": { "StatusCode": 206, "LastSeen": "2025-03-19T11:52:40.942477-04:00" From 142d44e0bef82334e0cfd1c80d748f64b4505785 Mon Sep 17 00:00:00 2001 From: Nate W Date: Sat, 31 May 2025 13:20:11 -0700 Subject: [PATCH 014/104] adding Daniel to staff list (#316) * adding Daniel to staff list Signed-off-by: Nate W * formatting and spelling Signed-off-by: Nate W --------- Signed-off-by: Nate W Signed-off-by: Bruce Hamilton --- .cspell.yml | 2 ++ README.md | 6 ++++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 8dda349..b3023b1 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -27,9 +27,11 @@ words: - Docsy - keda - kedacore + - krook - nate - subpages - techdocs - toolkits - toto - triaging + - w. diff --git a/README.md b/README.md index 13a400e..3fcd548 100644 --- a/README.md +++ b/README.md @@ -35,8 +35,10 @@ documentation. For details, see the TechDocs The full-time staff of the team is (in alphabetical order): -- [Nate Waddington](https://github.com/nate-double-u) - Head of mentoring & - documentation +- [Daniel Krook](https://github.com/krook) - Senior director of developer + experience, CNCF +- [Nate W.](https://github.com/nate-double-u) - Head of mentoring & + documentation, CNCF - [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead - [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate From e2e9841cb709d016413998953e2095c929df7458 Mon Sep 17 00:00:00 2001 From: Nate W Date: Sat, 31 May 2025 13:55:12 -0700 Subject: [PATCH 015/104] removing mention of alphabetizing the staff list Signed-off-by: Nate W Signed-off-by: Bruce Hamilton --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3fcd548..cd5031b 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ documentation. For details, see the TechDocs ## CNCF TechDocs team -The full-time staff of the team is (in alphabetical order): +The full-time staff of the team is: - [Daniel Krook](https://github.com/krook) - Senior director of developer experience, CNCF From b6f41adaed28cb6c3526640b7e62a33a87431e5e Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 14 Jun 2025 14:42:10 -0400 Subject: [PATCH 016/104] Update refcache: Add Daniel's GH handle (#319) Signed-off-by: Bruce Hamilton --- static/refcache.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/static/refcache.json b/static/refcache.json index 1b5b4d9..82bdf37 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -415,6 +415,10 @@ "StatusCode": 206, "LastSeen": "2025-03-19T11:52:42.574544-04:00" }, + "https://github.com/krook": { + "StatusCode": 206, + "LastSeen": "2025-06-14T10:39:11.530306-04:00" + }, "https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html": { "StatusCode": 206, "LastSeen": "2025-03-19T11:52:43.580609-04:00" From 3515b26ed6c5f3eec4fc711827d4664f06a0deed Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 14 Jun 2025 14:56:24 -0400 Subject: [PATCH 017/104] [CI] Update packages (#321) Signed-off-by: Bruce Hamilton --- package.json | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/package.json b/package.json index 3fc71a6..db428f3 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)", "_check:format": "npx prettier --check .", "_check:links": "make --keep-going check-links", - "_check:links-md": "bash -c 'for f in *.md `find analyses -name \"*.md\"`; do npx markdown-link-check@3.12.2 --config .markdown-link-check.json -p -v $f || exit 1; done'", + "_check:links-md": "bash -c 'for f in *.md `find analyses -name \"*.md\"`; do npx markdown-link-check --config .markdown-link-check.json -p -v $f || exit 1; done'", "_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", @@ -43,27 +43,26 @@ }, "author": "CNCF", "license": "CC-BY-4.0", - "NOTE": "We've pinned markdown-link-check to 3.12.2 due to a bug in 3.13.x stream, both in the devDeps below and the check:links script above. For details, see https://github.com/tcort/markdown-link-check/issues/369.", "dependencies": { - "@docusaurus/core": "3.7.0", - "@docusaurus/preset-classic": "3.7.0", - "@mdx-js/react": "^3.0.0", - "clsx": "^2.0.0", - "prism-react-renderer": "^2.3.0", - "react": "^19.0.0", - "react-dom": "^19.0.0" + "@docusaurus/core": "3.8.1", + "@docusaurus/preset-classic": "3.8.1", + "@mdx-js/react": "^3.1.0", + "clsx": "^2.1.1", + "prism-react-renderer": "^2.4.1", + "react": "^19.1.0", + "react-dom": "^19.1.0" }, "devDependencies": { - "cspell": "^8.17.5", - "markdown-link-check": "3.12.2", - "markdownlint": "^0.37.4", - "markdownlint-cli": "^0.44.0", - "npm-check-updates": "^17.1.15", - "prettier": "^3.5.2", - "@docusaurus/module-type-aliases": "3.7.0", - "@docusaurus/tsconfig": "3.7.0", - "@docusaurus/types": "3.7.0", - "typescript": "~5.6.2" + "cspell": "^9.1.1", + "markdown-link-check": "3.13.7", + "markdownlint": "^0.38.0", + "markdownlint-cli": "^0.45.0", + "npm-check-updates": "^18.0.1", + "prettier": "^3.5.3", + "@docusaurus/module-type-aliases": "3.8.1", + "@docusaurus/tsconfig": "3.8.1", + "@docusaurus/types": "3.8.1", + "typescript": "~5.8.3" }, "private": true, "spelling": "cSpell:ignore ACMR loglevel pkgs -", From 02a5e7b439d34c7eb3c6dff77c2917d47c63ef75 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 14 Jun 2025 15:07:48 -0400 Subject: [PATCH 018/104] [docs] Use canonical path in link (#322) Signed-off-by: Bruce Hamilton --- docs/localization/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/localization/README.md b/docs/localization/README.md index 9ca8025..b7aee9c 100644 --- a/docs/localization/README.md +++ b/docs/localization/README.md @@ -14,4 +14,4 @@ Guides here must not violate copyright or licensing requirements. ## Localizations -- [Japanese](ja/README.md) +- [Japanese](ja/) From f3132402b71da411ce6d9aea7945930129a76674 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 16 Jun 2025 14:07:26 -0400 Subject: [PATCH 019/104] Rename {analyses,docs}/**/README.md to index.md (#323) Signed-off-by: Bruce Hamilton --- .markdownlint.yaml | 1 + analyses/0001-contour.md | 1 + analyses/0002-notary-project.md | 1 + analyses/0003-krator.md | 1 + analyses/0004-tremor.md | 1 + analyses/0005-fluxcd.md | 1 + analyses/0006-gateway-api.md | 1 + analyses/0007-porter.md | 1 + analyses/0008-backstage/backstage-glossary.md | 4 + .../backstage-insights-summary.md | 1 + analyses/0008-backstage/backstage-issues.md | 4 + .../0008-backstage/{README.md => index.md} | 0 analyses/0008-backstage/user-roles.md | 4 + analyses/0009-in-toto/in-toto-analysis.md | 4 + analyses/0009-in-toto/in-toto-doc-issues.md | 4 + .../0009-in-toto/in-toto-implementation.md | 1 + analyses/0009-in-toto/{README.md => index.md} | 4 + .../0009-in-toto/survey-of-existing-doc.md | 4 + analyses/0010-etcd/{README.md => index.md} | 0 analyses/0011-keda/{README.md => index.md} | 0 analyses/0012-TUF/{README.md => index.md} | 1 + analyses/{README.md => index.md} | 4 + docs/analysis/criteria.md | 4 + docs/analysis/howto.md | 6 +- docs/analysis/{README.md => index.md} | 4 + .../templates/{README.md => index.md} | 4 + docs/analytics/{README.md => index.md} | 4 + docs/analytics/ua-to-ga4.md | 1 + docs/assistance.md | 4 + docs/hugo-and-docsy.md | 4 + docs/{README.md => index.md} | 5 + docs/localization/{README.md => index.md} | 4 + docs/localization/ja/{README.md => index.md} | 4 + docs/netlify-domains-setup.md | 1 + docs/repo-setup.md | 1 + docs/sandbox-doc-primer.md | 4 + docs/searching-documentation.md | 4 + docs/services.md | 4 + docs/versioning-documentation.md | 1 + docs/website-guidelines-checklist.md | 4 + scripts/add-frontmatter.mjs | 100 ++++++++++++++++++ 41 files changed, 205 insertions(+), 1 deletion(-) rename analyses/0008-backstage/{README.md => index.md} (100%) rename analyses/0009-in-toto/{README.md => index.md} (98%) rename analyses/0010-etcd/{README.md => index.md} (100%) rename analyses/0011-keda/{README.md => index.md} (100%) rename analyses/0012-TUF/{README.md => index.md} (96%) rename analyses/{README.md => index.md} (98%) rename docs/analysis/{README.md => index.md} (87%) rename docs/analysis/templates/{README.md => index.md} (94%) rename docs/analytics/{README.md => index.md} (97%) rename docs/{README.md => index.md} (80%) rename docs/localization/{README.md => index.md} (92%) rename docs/localization/ja/{README.md => index.md} (98%) create mode 100644 scripts/add-frontmatter.mjs diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 4a8c589..e93a196 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -4,3 +4,4 @@ list-marker-space: false no-inline-html: false no-bare-urls: false +single-h1: false # Temporary diff --git a/analyses/0001-contour.md b/analyses/0001-contour.md index 1a2dfe3..f5b0f1f 100644 --- a/analyses/0001-contour.md +++ b/analyses/0001-contour.md @@ -1,4 +1,5 @@ --- +title: Docs assessment cSpell:ignore: Horgan celestehorgan hashlinks --- diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md index 917390e..bb1b7eb 100644 --- a/analyses/0002-notary-project.md +++ b/analyses/0002-notary-project.md @@ -1,4 +1,5 @@ --- +title: Notary Project Docs Assessment cSpell:ignore: docset notaryproject celestehorgan --- diff --git a/analyses/0003-krator.md b/analyses/0003-krator.md index 532e6fe..9e6f5c6 100644 --- a/analyses/0003-krator.md +++ b/analyses/0003-krator.md @@ -1,4 +1,5 @@ --- +title: Krator Docs assessment cSpell:ignore: Krator celestehorgan CODEOWNERS --- diff --git a/analyses/0004-tremor.md b/analyses/0004-tremor.md index 94b3502..71500f9 100644 --- a/analyses/0004-tremor.md +++ b/analyses/0004-tremor.md @@ -1,4 +1,5 @@ --- +title: 'Assessment: Project Tremor' cSpell:ignore: Horgan onramps offramps LLDB Wayfair --- diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md index 2e0a37e..e5f2675 100644 --- a/analyses/0005-fluxcd.md +++ b/analyses/0005-fluxcd.md @@ -1,4 +1,5 @@ --- +title: Assessment template cSpell:ignore: celestehorgan Horgan --- diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md index fcfd42a..ed1433e 100644 --- a/analyses/0006-gateway-api.md +++ b/analyses/0006-gateway-api.md @@ -1,4 +1,5 @@ --- +title: 'Assessment: Project Kubernetes Gateway API' cSpell:ignore: Meha Bhalodiya mehabhalodiya kubernetes --- diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md index 88c52b9..d9e3bf0 100644 --- a/analyses/0007-porter.md +++ b/analyses/0007-porter.md @@ -1,4 +1,5 @@ --- +title: Porter Docs Analysis cSpell:ignore: Uchechukwu Obasi --- diff --git a/analyses/0008-backstage/backstage-glossary.md b/analyses/0008-backstage/backstage-glossary.md index b369c9b..91c859f 100644 --- a/analyses/0008-backstage/backstage-glossary.md +++ b/analyses/0008-backstage/backstage-glossary.md @@ -1,3 +1,7 @@ +--- +title: Backstage Glossary +--- + # Backstage Glossary ## API diff --git a/analyses/0008-backstage/backstage-insights-summary.md b/analyses/0008-backstage/backstage-insights-summary.md index 170487f..ace5664 100644 --- a/analyses/0008-backstage/backstage-insights-summary.md +++ b/analyses/0008-backstage/backstage-insights-summary.md @@ -1,4 +1,5 @@ --- +title: Backstage Insights cSpell:ignore: flipside --- diff --git a/analyses/0008-backstage/backstage-issues.md b/analyses/0008-backstage/backstage-issues.md index b07ab00..2e0c52a 100644 --- a/analyses/0008-backstage/backstage-issues.md +++ b/analyses/0008-backstage/backstage-issues.md @@ -1,3 +1,7 @@ +--- +title: Backstage umbrella issue +--- + # Backstage umbrella issue ## Overview diff --git a/analyses/0008-backstage/README.md b/analyses/0008-backstage/index.md similarity index 100% rename from analyses/0008-backstage/README.md rename to analyses/0008-backstage/index.md diff --git a/analyses/0008-backstage/user-roles.md b/analyses/0008-backstage/user-roles.md index e749f48..d44fd81 100644 --- a/analyses/0008-backstage/user-roles.md +++ b/analyses/0008-backstage/user-roles.md @@ -1,3 +1,7 @@ +--- +title: Backstage User Roles for Doc +--- + # Backstage User Roles for Doc This document provides recommendations for user roles, or personas, for diff --git a/analyses/0009-in-toto/in-toto-analysis.md b/analyses/0009-in-toto/in-toto-analysis.md index a7fd243..be8d5b5 100644 --- a/analyses/0009-in-toto/in-toto-analysis.md +++ b/analyses/0009-in-toto/in-toto-analysis.md @@ -1,3 +1,7 @@ +--- +title: Analysis of Existing Documentation +--- + # Analysis of Existing Documentation This document characterizes the effectiveness and completeness of the in-toto diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md index b4a3163..fdc94a0 100644 --- a/analyses/0009-in-toto/in-toto-doc-issues.md +++ b/analyses/0009-in-toto/in-toto-doc-issues.md @@ -1,3 +1,7 @@ +--- +title: Documentation Issues +--- + # Documentation Issues These issues identify and classify tasks that contributors can undertake to diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md index b5b9c08..68f15f0 100644 --- a/analyses/0009-in-toto/in-toto-implementation.md +++ b/analyses/0009-in-toto/in-toto-implementation.md @@ -1,4 +1,5 @@ --- +title: Implementation cSpell:ignore: roadmaps Cappos --- diff --git a/analyses/0009-in-toto/README.md b/analyses/0009-in-toto/index.md similarity index 98% rename from analyses/0009-in-toto/README.md rename to analyses/0009-in-toto/index.md index 5367d5f..818c644 100644 --- a/analyses/0009-in-toto/README.md +++ b/analyses/0009-in-toto/index.md @@ -1,3 +1,7 @@ +--- +title: README +--- + # README These documents are intended to recommend a direction for the ongoing diff --git a/analyses/0009-in-toto/survey-of-existing-doc.md b/analyses/0009-in-toto/survey-of-existing-doc.md index 55fb1fe..b9903c8 100644 --- a/analyses/0009-in-toto/survey-of-existing-doc.md +++ b/analyses/0009-in-toto/survey-of-existing-doc.md @@ -1,3 +1,7 @@ +--- +title: Survey of existing documentation as of 09/2023 +--- + # Survey of existing documentation as of 09/2023 The following links are loosely sorted into conceptual categories. diff --git a/analyses/0010-etcd/README.md b/analyses/0010-etcd/index.md similarity index 100% rename from analyses/0010-etcd/README.md rename to analyses/0010-etcd/index.md diff --git a/analyses/0011-keda/README.md b/analyses/0011-keda/index.md similarity index 100% rename from analyses/0011-keda/README.md rename to analyses/0011-keda/index.md diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/index.md similarity index 96% rename from analyses/0012-TUF/README.md rename to analyses/0012-TUF/index.md index 7255225..81e3de6 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/index.md @@ -1,4 +1,5 @@ --- +title: TUF Documentation Analysis cSpell:ignore: theupdateframework --- diff --git a/analyses/README.md b/analyses/index.md similarity index 98% rename from analyses/README.md rename to analyses/index.md index e8fa04b..e4c9eae 100644 --- a/analyses/README.md +++ b/analyses/index.md @@ -1,3 +1,7 @@ +--- +title: TechDocs Analysis for CNCF Projects +--- + # TechDocs Analysis for CNCF Projects diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 8ce5107..9045bb0 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -1,3 +1,7 @@ +--- +title: Assessment criteria and examples +--- + # Assessment criteria and examples We recommend reading the diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index aea4e93..19a7182 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -1,3 +1,7 @@ +--- +title: CNCF TechDocs Analysis How-To +--- + # CNCF TechDocs Analysis How-To ## Audience @@ -217,5 +221,5 @@ Create issues in the project documentation GitHub repository for: [analyses]: ../../analyses/ [criteria]: ./criteria.md [project maturity level]: https://www.cncf.io/project-metrics -[templates]: ./templates/README.md +[templates]: ./templates/index.md [issues list]: ./templates/issues-list.md diff --git a/docs/analysis/README.md b/docs/analysis/index.md similarity index 87% rename from docs/analysis/README.md rename to docs/analysis/index.md index 195a967..fd73d1c 100644 --- a/docs/analysis/README.md +++ b/docs/analysis/index.md @@ -1,3 +1,7 @@ +--- +title: TechDoc Analysis +--- + # TechDoc Analysis This section contains instructions and criteria for completing a documentation diff --git a/docs/analysis/templates/README.md b/docs/analysis/templates/index.md similarity index 94% rename from docs/analysis/templates/README.md rename to docs/analysis/templates/index.md index 164e410..0865fb0 100644 --- a/docs/analysis/templates/README.md +++ b/docs/analysis/templates/index.md @@ -1,3 +1,7 @@ +--- +title: TechDoc Analysis Templates +--- + # TechDoc Analysis Templates This section contains templates for analyzing a CNCF project's documentation. diff --git a/docs/analytics/README.md b/docs/analytics/index.md similarity index 97% rename from docs/analytics/README.md rename to docs/analytics/index.md index cc198c7..9567cbb 100644 --- a/docs/analytics/README.md +++ b/docs/analytics/index.md @@ -1,3 +1,7 @@ +--- +title: Analytics +--- + # Analytics ## Google Analytics diff --git a/docs/analytics/ua-to-ga4.md b/docs/analytics/ua-to-ga4.md index 79733ef..3855f90 100644 --- a/docs/analytics/ua-to-ga4.md +++ b/docs/analytics/ua-to-ga4.md @@ -1,4 +1,5 @@ --- +title: Migrating Universal to Google Analytics 4 cSpell:ignore: gtag kubernetes --- diff --git a/docs/assistance.md b/docs/assistance.md index 5362657..cbbd309 100644 --- a/docs/assistance.md +++ b/docs/assistance.md @@ -1,3 +1,7 @@ +--- +title: Assistance program for technical documentation +--- + # Assistance program for technical documentation This document outlines the Cloud Native Computing Foundation (CNCF) Technical diff --git a/docs/hugo-and-docsy.md b/docs/hugo-and-docsy.md index 4915534..2ff580c 100644 --- a/docs/hugo-and-docsy.md +++ b/docs/hugo-and-docsy.md @@ -1,3 +1,7 @@ +--- +title: Hugo and Docsy +--- + # Hugo and Docsy Tips: diff --git a/docs/README.md b/docs/index.md similarity index 80% rename from docs/README.md rename to docs/index.md index 9eec011..806cabd 100644 --- a/docs/README.md +++ b/docs/index.md @@ -1,3 +1,8 @@ +--- +title: CNCF Techdocs how-tos +sidebar_position: 1 +--- + # CNCF Techdocs how-tos This directory contains documentation on how the CNCF TechDocs team does things. diff --git a/docs/localization/README.md b/docs/localization/index.md similarity index 92% rename from docs/localization/README.md rename to docs/localization/index.md index b7aee9c..b560434 100644 --- a/docs/localization/README.md +++ b/docs/localization/index.md @@ -1,3 +1,7 @@ +--- +title: CNCF Localization Guides +--- + # CNCF Localization Guides This directory contains a growing collection of localization guides that CNCF diff --git a/docs/localization/ja/README.md b/docs/localization/ja/index.md similarity index 98% rename from docs/localization/ja/README.md rename to docs/localization/ja/index.md index 2a47790..442cae0 100644 --- a/docs/localization/ja/README.md +++ b/docs/localization/ja/index.md @@ -1,3 +1,7 @@ +--- +title: CNCF日本語ローカライゼーション向けガイドライン +--- + # CNCF日本語ローカライゼーション向けガイドライン このドキュメントでは、CNCFのプロジェクトをローカライズする際に参考になる一般的なガイドラインを提供します。 diff --git a/docs/netlify-domains-setup.md b/docs/netlify-domains-setup.md index 94351d4..f859170 100644 --- a/docs/netlify-domains-setup.md +++ b/docs/netlify-domains-setup.md @@ -1,4 +1,5 @@ --- +title: Netlify and domain setup cSpell:ignore: caniszczyk --- diff --git a/docs/repo-setup.md b/docs/repo-setup.md index e58fb20..bf7003c 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -1,4 +1,5 @@ --- +title: Repository setup cSpell:ignore: cncf --- diff --git a/docs/sandbox-doc-primer.md b/docs/sandbox-doc-primer.md index 43c6a63..f95e8e7 100644 --- a/docs/sandbox-doc-primer.md +++ b/docs/sandbox-doc-primer.md @@ -1,3 +1,7 @@ +--- +title: CNCF sandbox project documentation primer +--- + # CNCF sandbox project documentation primer This document is a quick primer for CNCF project maintainers and contributors diff --git a/docs/searching-documentation.md b/docs/searching-documentation.md index c137ad2..539141e 100644 --- a/docs/searching-documentation.md +++ b/docs/searching-documentation.md @@ -1,3 +1,7 @@ +--- +title: Documentation Search +--- + # Documentation Search diff --git a/docs/services.md b/docs/services.md index 5d91e4f..455d321 100644 --- a/docs/services.md +++ b/docs/services.md @@ -1,3 +1,7 @@ +--- +title: Services for projects +--- + # Services for projects The CNCF provides technical writing and documentation website services for all diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md index 2a17b22..91aafde 100644 --- a/docs/versioning-documentation.md +++ b/docs/versioning-documentation.md @@ -1,4 +1,5 @@ --- +title: prettier-ignore # prettier-ignore cSpell:ignore: Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi --- diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index 685a4f6..936b1d2 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -1,3 +1,7 @@ +--- +title: CNCF website guidelines checklist +--- + # CNCF website guidelines checklist As per the diff --git a/scripts/add-frontmatter.mjs b/scripts/add-frontmatter.mjs new file mode 100644 index 0000000..933f529 --- /dev/null +++ b/scripts/add-frontmatter.mjs @@ -0,0 +1,100 @@ +import { readFile, writeFile } from 'fs/promises'; +import { glob } from 'glob'; +import path from 'path'; + +// Regular expression to match frontmatter +const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/; + +// Regular expression to match first heading +const headingRegex = /^#\s+(.+)$/m; + +// Regular expression to match title in frontmatter +const titleRegex = /^title:\s*(.+)$/m; + +async function processFile(filePath) { + try { + const content = await readFile(filePath, 'utf-8'); + const headingMatch = content.match(headingRegex); + + if (!headingMatch) { + console.log(`Warning: ${filePath} has no heading to use as title`); + return; + } + + const headingTitle = headingMatch[1].trim(); + let hasFrontmatter = false; + let existingTitle = null; + let contentWithoutFrontmatter = content; + let existingFrontmatter = ''; + + // Check for existing frontmatter + const frontmatterMatch = content.match(frontmatterRegex); + if (frontmatterMatch) { + hasFrontmatter = true; + existingFrontmatter = frontmatterMatch[1]; + contentWithoutFrontmatter = content.slice(frontmatterMatch[0].length); + + // Check if title already exists + const titleMatch = existingFrontmatter.match(titleRegex); + if (titleMatch) { + existingTitle = titleMatch[1].trim(); + } + } + + // Only update if: + // 1. No frontmatter exists, or + // 2. Frontmatter exists but has no title, or + // 3. Frontmatter title doesn't match the heading + const needsUpdate = !hasFrontmatter || !existingTitle; + // || existingTitle !== headingTitle + if (needsUpdate) { + let newFrontmatter; + const formattedTitle = headingTitle.includes(':') + ? `'${headingTitle}'` + : headingTitle; + if (hasFrontmatter) { + // Remove existing title if it exists + const frontmatterWithoutTitle = existingFrontmatter + .replace(titleRegex, '') + .trim(); + newFrontmatter = `title: ${formattedTitle}${frontmatterWithoutTitle ? '\n' + frontmatterWithoutTitle : ''}`; + } else { + newFrontmatter = `title: ${formattedTitle}`; + } + + const newContent = `--- +${newFrontmatter} +---\n +${contentWithoutFrontmatter}`; + + await writeFile(filePath, newContent); + console.log( + `${hasFrontmatter ? 'Updated' : 'Added'} frontmatter to ${filePath}`, + ); + } else { + console.log(`Skipping ${filePath} - frontmatter title matches heading`); + } + } catch (error) { + console.error(`Error processing ${filePath}:`, error); + } +} + +async function main() { + try { + // Find all markdown files in docs directory + const files = await glob('{analyses,docs}/**/*.md'); + console.log(`Found ${files.length} markdown files`); + + // Process each file + for (const file of files) { + await processFile(file); + } + + console.log('Done!'); + } catch (error) { + console.error('Error:', error); + process.exit(1); + } +} + +main(); From ad5cef0a24fc1ac224f5876e21a0cc237e9a205b Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 17 Jun 2025 11:39:07 -0400 Subject: [PATCH 020/104] Fix page title, adjust link-check scripts (#324) Signed-off-by: Bruce Hamilton --- .gitignore | 4 ++++ docs/versioning-documentation.md | 4 ++-- package.json | 5 +++-- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 8665d05..e6479db 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,10 @@ .cache-loader /build +# Astro +.astro +dist + # npm assets node_modules/ package-lock.json diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md index 91aafde..a1d7dfa 100644 --- a/docs/versioning-documentation.md +++ b/docs/versioning-documentation.md @@ -1,10 +1,10 @@ --- -title: prettier-ignore +title: Doc Versioning with Hugo & Netlify # prettier-ignore cSpell:ignore: Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi --- -# Technical Documentation Versioning with Hugo & Netlify +# Doc Versioning with Hugo & Netlify Technical Documents Versioning is an intersection of: diff --git a/package.json b/package.json index db428f3..b9170fe 100644 --- a/package.json +++ b/package.json @@ -7,8 +7,9 @@ "_check:format:any": "npx prettier --check --ignore-path ''", "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)", "_check:format": "npx prettier --check .", - "_check:links": "make --keep-going check-links", "_check:links-md": "bash -c 'for f in *.md `find analyses -name \"*.md\"`; do npx markdown-link-check --config .markdown-link-check.json -p -v $f || exit 1; done'", + "_check:links:internal": "npm run _check:links -- HTMLTEST_ARGS='--skip-external'", + "_check:links": "make --keep-going check-links", "_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", @@ -65,7 +66,7 @@ "typescript": "~5.8.3" }, "private": true, - "spelling": "cSpell:ignore ACMR loglevel pkgs -", + "spelling": "cSpell:ignore ACMR HTMLTEST loglevel pkgs -", "prettier": { "proseWrap": "always", "singleQuote": true From 44768a0179b753dd7cc90fe5f7fe89659f946989 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 18 Jun 2025 05:28:08 -0400 Subject: [PATCH 021/104] Link, title, and filename adjustments (#325) Signed-off-by: Bruce Hamilton --- .cspell.yml | 5 ++--- docs/analysis/templates/analysis.md | 10 +++++----- docs/index.md | 4 ++-- docs/sandbox-doc-primer.md | 10 ++++++---- docs/{searching-documentation.md => search.md} | 5 +++-- docs/{versioning-documentation.md => versioning.md} | 4 ++-- docs/website-guidelines-checklist.md | 6 +++--- 7 files changed, 23 insertions(+), 21 deletions(-) rename docs/{searching-documentation.md => search.md} (97%) rename docs/{versioning-documentation.md => versioning.md} (99%) diff --git a/.cspell.yml b/.cspell.yml index b3023b1..16e7762 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -5,7 +5,7 @@ version: '0.2' caseSensitive: true ignorePaths: - '*.csv' - - /docs/localization/ja + - /docs/[Ll]ocalization/ja # cSpell:disable-line # patterns: # - name: CodeBlock # pattern: | @@ -20,7 +20,6 @@ ignorePaths: # ignoreRegExpList: # - CodeBlock words: - - nvmrc - backstore - CLOTributor - CNCF @@ -29,9 +28,9 @@ words: - kedacore - krook - nate + - nvmrc - subpages - techdocs - toolkits - toto - triaging - - w. diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index 5581011..e6103fa 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -115,9 +115,9 @@ Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: -- [Project documentation](?TODO=ADD-URL) -- [Contributor documentation](?TODO=ADD-URL) -- [Website and documentation infrastructure](?TODO=ADD-URL) +- [Project documentation](./?TODO=ADD-URL) +- [Contributor documentation](./?TODO=ADD-URL) +- [Website and documentation infrastructure](./?TODO=ADD-URL) Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. @@ -550,8 +550,8 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-doc-website]: ?_PROJECT-DOC-URL_ -[project-website]: ?_PROJECT-WEBSITE_ +[project-doc-website]: ./?_PROJECT-DOC-URL_ +[project-website]: ./?_PROJECT-WEBSITE_ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md diff --git a/docs/index.md b/docs/index.md index 806cabd..9f616fb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,6 +5,6 @@ sidebar_position: 1 # CNCF Techdocs how-tos -This directory contains documentation on how the CNCF TechDocs team does things. +This section contains documentation on how the CNCF TechDocs team does things. While its intent is for the CNCF TechDocs team's use, we encourage project -maintainers to use these documents if you find them helpful! +maintainers to use these documents if you find them helpful. diff --git a/docs/sandbox-doc-primer.md b/docs/sandbox-doc-primer.md index f95e8e7..c81067b 100644 --- a/docs/sandbox-doc-primer.md +++ b/docs/sandbox-doc-primer.md @@ -1,11 +1,13 @@ --- -title: CNCF sandbox project documentation primer +title: CNCF sandbox-project docs primer +sidebar: + label: Sandbox-project docs primer --- -# CNCF sandbox project documentation primer +# CNCF sandbox-project docs primer -This document is a quick primer for CNCF project maintainers and contributors -who need to document their projects but don't know where to start. It provides a +This page is a quick primer for CNCF project maintainers and contributors who +need to document their projects but don't know where to start. It provides a framework for thinking about user documentation that will enable the project contributors to write effective documentation from the very beginning and to get the most out of documentation efforts as the project matures. diff --git a/docs/searching-documentation.md b/docs/search.md similarity index 97% rename from docs/searching-documentation.md rename to docs/search.md index 539141e..d97a52d 100644 --- a/docs/searching-documentation.md +++ b/docs/search.md @@ -1,8 +1,9 @@ --- -title: Documentation Search +title: Site Search +sidebar: { label: Search } --- -# Documentation Search +# Site Search diff --git a/docs/versioning-documentation.md b/docs/versioning.md similarity index 99% rename from docs/versioning-documentation.md rename to docs/versioning.md index a1d7dfa..d66ae19 100644 --- a/docs/versioning-documentation.md +++ b/docs/versioning.md @@ -1,10 +1,10 @@ --- -title: Doc Versioning with Hugo & Netlify +title: Versioned docs with Hugo & Netlify # prettier-ignore cSpell:ignore: Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi --- -# Doc Versioning with Hugo & Netlify +# Versioned docs with Hugo & Netlify Technical Documents Versioning is an intersection of: diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index 936b1d2..539c367 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -1,10 +1,10 @@ --- -title: CNCF website guidelines checklist +title: Website guidelines & checklist --- -# CNCF website guidelines checklist +# Website guidelines & checklist -As per the +Per the [CNCF Website Guidelines](https://github.com/cncf/foundation/blob/main/website-guidelines.md), the following should be present:
_Note_, not all of these are applicable to all projects From 91761927cdac38a90915b93dd794828803d1a619 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 18 Jun 2025 07:16:14 -0400 Subject: [PATCH 022/104] Canonicalize README links, cleanup package.json (#326) Signed-off-by: Bruce Hamilton --- README.md | 4 ++-- package.json | 50 ++++++++++++++++++++++++++------------------------ 2 files changed, 28 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index cd5031b..ed38a74 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@ This site contains resources provided by the CNCF Technical Documentation team, including: -- [Docs](docs) about building websites and developing technical documentation, +- [Docs](docs/) about building websites and developing technical documentation, including recommended tools, best practices, how-tos, and evaluation checklists. It provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](docs/analysis/). -- [Analyses](analyses): a collection of documentation analyses of CNCF projects +- [Analyses](analyses/): a collection of documentation analyses of CNCF projects performed by the TechDocs team. ## TechDocs Q&A diff --git a/package.json b/package.json index b9170fe..685fd9d 100644 --- a/package.json +++ b/package.json @@ -3,44 +3,46 @@ "version": "0.0.0", "description": "Resources provided by the CNCF Technical Documentation team.", "scripts": { - "_build": "docusaurus build", + "_build": "npm run docus:build", "_check:format:any": "npx prettier --check --ignore-path ''", "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)", "_check:format": "npx prettier --check .", "_check:links-md": "bash -c 'for f in *.md `find analyses -name \"*.md\"`; do npx markdown-link-check --config .markdown-link-check.json -p -v $f || exit 1; done'", "_check:links:internal": "npm run _check:links -- HTMLTEST_ARGS='--skip-external'", "_check:links": "make --keep-going check-links", + "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", "_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", - "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", - "_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'", + "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'", "_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path '*/00*'", "_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010'", - "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'", "_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'", + "_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'", + "build:preview": "npm run _build", + "build:production": "npm run _build", + "build": "BUILD_ENV=dev npm run _build", "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)", "check:links": "npm run _check:links", "check:markdown": "npm run _check:markdown:all", "check:spelling": "npx cspell --no-progress -c .cspell.yml analyses docs *.md", "check": "npm run seq -- $(npm run -s _list:check:*)", + "docus:build": "docusaurus build", + "docus:clear": "docusaurus clear", + "docus:deploy": "docusaurus deploy", + "docus:serve": "docusaurus serve", + "docus:start": "docusaurus start", + "docus:swizzle": "docusaurus swizzle", + "docus:write-heading-ids": "docusaurus write-heading-ids", + "docus:write-translations": "docusaurus write-translations", + "docusaurus": "docusaurus", "fix:format": "npm run _check:format -- --write", "fix": "npm run seq -- $(npm -s run _list:fix:*)", "precheck:links": "npm run build", "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ", + "serve": "npm run docus:serve", "test": "npm run check", - "update:pkgs": "npx npm-check-updates -u", - "docusaurus": "docusaurus", - "start": "docusaurus start", - "build:preview": "npm run _build", - "build:production": "npm run _build", - "build": "BUILD_ENV=dev npm run _build", - "swizzle": "docusaurus swizzle", - "deploy": "docusaurus deploy", - "clear": "docusaurus clear", - "serve": "docusaurus serve", - "write-translations": "docusaurus write-translations", - "write-heading-ids": "docusaurus write-heading-ids", - "typecheck": "tsc" + "typecheck": "tsc", + "update:pkgs": "npx npm-check-updates -u" }, "author": "CNCF", "license": "CC-BY-4.0", @@ -50,23 +52,23 @@ "@mdx-js/react": "^3.1.0", "clsx": "^2.1.1", "prism-react-renderer": "^2.4.1", - "react": "^19.1.0", - "react-dom": "^19.1.0" + "react-dom": "^19.1.0", + "react": "^19.1.0" }, "devDependencies": { + "@docusaurus/module-type-aliases": "3.8.1", + "@docusaurus/tsconfig": "3.8.1", + "@docusaurus/types": "3.8.1", "cspell": "^9.1.1", "markdown-link-check": "3.13.7", - "markdownlint": "^0.38.0", "markdownlint-cli": "^0.45.0", + "markdownlint": "^0.38.0", "npm-check-updates": "^18.0.1", "prettier": "^3.5.3", - "@docusaurus/module-type-aliases": "3.8.1", - "@docusaurus/tsconfig": "3.8.1", - "@docusaurus/types": "3.8.1", "typescript": "~5.8.3" }, "private": true, - "spelling": "cSpell:ignore ACMR HTMLTEST loglevel pkgs -", + "spelling": "cSpell:ignore ACMR docus HTMLTEST loglevel pkgs -", "prettier": { "proseWrap": "always", "singleQuote": true From af88d50f25822622d1d170fae458dc5338febf9c Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Tue, 5 Aug 2025 15:44:07 -0700 Subject: [PATCH 023/104] Add Knative TechDoc analysis and issues list. (#329) Signed-off-by: Dave Welsch Signed-off-by: Bruce Hamilton --- analyses/0015-knative/analysis.md | 864 ++++++++++++++++++++++++++++++ analyses/0015-knative/issues.md | 721 +++++++++++++++++++++++++ 2 files changed, 1585 insertions(+) create mode 100644 analyses/0015-knative/analysis.md create mode 100644 analyses/0015-knative/issues.md diff --git a/analyses/0015-knative/analysis.md b/analyses/0015-knative/analysis.md new file mode 100644 index 0000000..e985156 --- /dev/null +++ b/analyses/0015-knative/analysis.md @@ -0,0 +1,864 @@ +--- +title: Knative Documentation Analysis +tags: Knative +created: 2025-07-25 +modified: 2025-07-25 +author: Dave Welsch (@dwelsch-esi) +--- + + + +## Introduction + +This document analyzes the effectiveness and completeness of the +[Knative][project-website] open source software (OSS) project's documentation +and website. It is funded by the CNCF Foundation as part of its overall effort +to incubate, grow, and graduate open source cloud native software projects. + +According to CNCF best practices guidelines, effective documentation is a +prerequisite for program graduation. The documentation analysis is the first +step of a CNCF process aimed at assisting projects with their documentation +efforts. + +### Purpose + +This document was written to analyze the current state of Knative +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second +document is a list of [issues] to be added to the project +documentation repository. These issues can be taken up by contributors to +improve the documentation. + +This document: + +- Analyzes the current Knative technical documentation and website +- Compares existing documentation against the CNCF’s standards +- Recommends a program of key improvements with the largest return on investment + +### Scope of analysis + +The documentation discussed here includes the entire contents of the website, +the technical documentation, and documentation for contributors and users on the +Knative GitHub repository. + +The Knative website and documentation are written in Markdown and are compiled +using the mkdocs static site generator with the Material theme. +The site's code is stored on the knative/docs GitHub repo. + +#### In scope + +- Website: https://knative.dev/docs/ (not an error; identical to the + Documentation site) +- Documentation: https://knative.dev/docs/ +- Website repo: https://github.com/knative/docs +- https://github.com/knative/eventing (The Knative Eventing API is built from + this repo) +- https://github.com/knative/community (Community and governance for the + project) +- https://github.com/knative/client (`kn`, a Knative CLI) +- https://github.com/knative/func (`func`, another CLI) +- https://github.com/knative/serving (a major component of Knative) + +#### Out of scope + +- Other Knative repos: https://github.com/knative/\, for any \ not + listed in "In scope". + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** concerns documentation for users of the Knative + software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Knative OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability + +Each section begins with summary ratings based on a rubric with appropriate +[criteria] for the section, then proceeds to: + +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help Knative users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [issues] document contains actionable improvements +for inclusion in [project-doc-website]/issues. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the **[issues] list**. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation](#project-documentation) +- [Contributor documentation](#contributor-documentation) +- [Website and documentation infrastructure](#website-and-infrastructure) + +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria] specification. + +#### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards, +and suggests possible improvements. In most cases there is more than one way to +do things. Few recommendations here are meant to be prescriptive. Rather, the +recommended implementations represent the reviewers' experience with how to +apply documentation best practices. In other words, borrowing terminology from +the lexicon of [RFCs][rfc-spec], the changes described here should be understood +as "recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. + +## Project documentation + +Knative is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| Criterion | [Rating (1-5)] | +| -------------------------- | -------------- | +| Information architecture | 2 - Needs improvement | +| New user content | 2 - Needs improvement | +| Content maintainability | 3 - Meets standards | +| Content creation processes | 3 - Meets standards | +| Inclusive language | 5 - Exemplary | + +### Comments + +Project documentation overall is very good. There's room for improvement mostly +around organization and the new user experience. + +Following are general comments that don't address specific CNCF criteria. + +The project main landing page also serves as the documentation landing page, +mixing marketing and technical information. It's helpful to users if there's +a clear separation between technical documentation and other information. +The technical documentation is goal-driven and should be factual, specific, +and purposeful. + +The technical documentation outline in the banner headings is good from a +organizational perspective: Concepts, Tutorial, and Installing, then +instructional information, then reference information. See notes below on the +Left-hand sidebar (LHS) table of contents. Some other notes: + +- The "Home" item is unnecessary for the project landing page. By convention +the upper-left logo links to the site landing page. +- The "Concepts" section is a brief introduction. Instead, it should contain +a complete technical overview that's accessible to a new user. +- "Installing" does a good job of providing complete installation instructions +for all user roles. Some additional "road signs" would help to guide users to +the correct installation for their role, OS, and so on. +- "Serving" and "Eventing" organize the instructional information by functional + component, and by user role within the component. The alternative is to flip + this and organize by user role first: + - Admin Guide + - Eventing + - Serving + - Developer Guide + - Eventing + - Serviing +- Knative CLI - The title implies a dedicated Knative CLI. There are two Knative + CLIs documented here, `kn` and `func`. As well, `kubectl` is the first CLI + documented on the page. + +The `kn` CLI is documented in the knative/client repo, with a link from here. +The reference to the repo-based documentation is OK, but why is the not +documented here? Its installation is documented on the site; this seems +inconsistent. + +***Table of contents*** + +The table of contents (TOC) in the LHS is hard to navigate. Some issues: + +1. The LHS contains only one technical documentation section at a time (see + previous comment about the banner menu). It's more usual for the LHS to + contain the entire TOC and to not change between pages (except for expanding + and collapsing headings). +2. The expand/collapse items in the TOC are navigational only; they do not + bring up information pages. This isn't uncommon, but it's tedious to navigate + multi-level topics. It's also less efficient than displaying the overview or + introduction with the top-level entry. +3. There are singleton sub-headings in the TOC. For example, see [Concepts > + Resources > Serving Resources > Revisions] + (https://knative.dev/development/concepts/serving-resources/revisions/). + Especially with the navigation-only expand/collapse items, these represent + extra mouse clicks for the user with no added benefit. +4. There are multiple entry points to the same documentation in the TOC. *And* + there are duplicate information sections. For example: + Installing > Install the Knative CLI sends you to the `Knative CLI` page. This + completely changes the left-hand TOC but the banner menu is not set up to + highlight `Knative CLI`, so are no cues as to where you were just teleported + (violating the [principle of least astonishment] + (https://en.wikipedia.org/wiki/Principle_of_least_astonishment)). + +***New user experience*** + +The blurb under "Need to know more?" on the landing page sounds like it's going +to an information resource; the button says "Explore Knative". Instead it +goes to the Quickstart tutorials. It sounds more like it should go to "Serving +Architecture". + +***Graphics*** + +In many places, large graphics are placed before any explanatory text. Also, +many graphics, especially in the E2E tutorial (incidentally, "end-to-end" should +be spelled out), provide no information but serve to distract, clutter, and take +up valuable screen space. + +***Headings and titles*** + +Tasks are for the most part well named using appropriate verbs. + +TOC titles that don't agree with page titles confuse the reader. + +The following subsections address individual items in the CNCF criteria for +Project Documentation. + +#### Information architecture + +***Is there high level conceptual content?*** + +The "Concepts" document at the top of the websiteis a brief introduction to two +of the components of Knative. It does not introduce the overall architecture or +explain how it works. + +There is other high-level conceptual information about Knative scattered +throughout the website. The existing conceptual information seems to assume that +you're already familiar with Kubernetes and with the problems that Knative is +intended to solve. + +***Is every product feature documented?*** + +The documentation seems a little behind being feature-complete, based on open +Github issues requesting feature documentation. See for example issues +[6216](https://github.com/knative/docs/issues/6216) and +[5331](https://github.com/knative/docs/issues/5331). + +Every component section (Eventing, Serving) is organized differently. This +requires extra cognitive work from the readers. + +***Does the documentation define all user roles (personas) for the product?*** + +The "Audiences information" in Community is a good description of user roles. +This information is reflected in subsections of the "Eventing" and "Serving" +sections in the division between Developer and Admin topics. + +***Are there instructions (tasks, tutorials) documented for features?*** + +Tasks are documented for most features. + +***Are there instructions for all major use cases for each user role?*** + +Tasks are covered for different user roles; it's unknown whether this coverage +is complete. + +***Are tasks organized by user role and use case?*** + +The documentation is organized by the key components. Tasks for each component +seem to be present, but could be more clearly written and better labeleled. + +***Does instructional content demonstrate atomicity*** +Are individual tasks clearly named according to their goals? + +For the most part tasks seem separate and well named. + +***Are tasks written as numbered step-by-step instructions?*** + +Tasks are broken down into steps. In most cases steps are not numbered. Some +procedures have embedded subtasks. Numbering of tasks and subtasks is +inconsistent. + +***Are task descriptions in headings and the TOC described with a verb phrase?*** + +Most task headings accurately describe the task. + +***Is the documentation free of features that lack task documentation?*** + +Task documentation seems to exist for key features. It is sometimes difficult to +locate. + +***Is the “happy path” — the most common use case — documented?*** + +The "Happy Path" seems to be building and running a simple service using all +three of the Knative components. This is documented in the "E2E" tutorial. + +***Is there a clear escalation path for users needing more help?*** + +In general, Knative help and community support are strong throughout the +documentation and repositories. Troubleshooting could provide clearer +instructions and be more closely linked to the tasks it supports. Readers will +probably eventually find their way to help through the community via a Slack +channel. + +There is a FAQ for Eventing. It contains only one question. + +There are troubleshooting instructions for various components within the +documentation. The troubleshooting steps are little more than command examples +showing the non-exception case output. In some cases the output is cryptic and +it's not clear what to do. + +***If the product exposes an API, is there a complete reference?*** + +There is a reference for the Eventing API. It contains no explanatory or +introductory text, and many descriptions of functions and fields are missing, +rudimentary, or tautological. + +***If the product has CLIs, are there complete references?*** + +There are references for the two CLIs, `kn` and `func`. The references are +contained in their respective repos, not in the technical documentation. + +***Is content up to date and accurate?*** + +The content seems up to date based on the versioning and release mechanisms. + +***Does the doc separate conceptual, instructional, and reference info?*** + +Individual topics are separated by information type. + + +#### New user content + +***Is “getting started” clearly labeled?** +(“Getting started”, “Installation”, “First steps”, or the equivalent.) + +There is no clearly labeleld "Getting Started" page. There is a "Quickstart" +tutorial, with an accompanying plugin, that serves (primarily) as a beginner +getting-started procedure. + +***Is there a “getting started” path for all user roles?*** + +The "Quckstart" tutorial does not discuss roles. It acknowledges that the +exercise does a simplified local installation and directs the reader to YAML or +Operator-based installs for production server installation. + +***Is installation documented step-by-step?*** + +Installation is thoroughly documented. Instructions are step-by-step and well +organized. That said, I could not install using the Quickstart tutorial because +I ran into an error that was not documented. the Install pages link to the +Release Notes pages for binary downloads. This was confusing. Downloading the +binary from the release page is not straightforward. The download links are +under "Assets", far down the page. + +***Are different types of installation documented if necessary?*** +(development, test, production) + +The Quickstart tutorial documents a local install. Other (server) installs are +documented in the Install section. + +***If needed, are multiple OSes documented?*** + +Installs for multiple OSes are documented implicitly (for example, the install +binaries are characteristic of their respective OSes). A discussion of OSes up +front in the prereqs section would be appropriate. + +***Do users know where to go after reading the getting started guide?*** + +Next steps are documented at the end of the quickstart and some other sections. + +***Is new user content clearly signposted on the site’s homepage?*** + +There is no clearly labeled new user content available from the landing page. +The closest is the Quickstart tutorial. + +***Is there easily copy-pastable sample code or other example content?*** + +There are code samples available in "Code samples", organized by Knative +component. + +#### Content maintainability and site mechanics + + +***Is your documentation searchable?*** + +The documentation is searchable. The Search function does not truncate results. +For example, the "Puppet" entry when searching "getting started" displays the +page's entire 900 words. + +***Are you planning for localization/internationalization?*** + +***Is a localization framework present?*** + +Apparently not. There is no evident localization or mechanism for localization. + +***Do you have a clearly documented method for versioning your content?*** + +Content is versioned up to the most recent release using branches in the +knative/docs Github repo. The process is documented in the contribute-to-docs +directory in the repo. The version drop-down contains the latest three releases +plus pre-release. No older archived versions are offered on the site. + +***Is release-specific information documented in release notes?*** + +The repo contains appropriate release notes. + +***Is the documentation free of duplicate sections of information?*** + +Duplicated information is present in the doc. It is deliberately included from a +collection of reusable doc snippets. + +***Do informational graphics add value by providing information?*** + +Graphics are large and contain little new information, especially in the E2E +tutorial. Some of the conceptual diagrams (component diagrams, flow charts) are +helpful. + +***Will graphics require modifications?*** +For example, due to software changes, GUI updates, or translation? + +Graphics are unlikely to require frequent updates; for example, there are no +screen shots. + + +#### Content creation processes + +***Is there a clearly documented contribution process for documentation?*** + +The documentation contribution process is well documented in the repo. + +***Does the code release process include documentation creation & updates?*** + +Documentation releases are controlled by the release process. The contribution +process documents how to update previous versions of the documentation, if +necessary. + +***Who reviews and approves documentation pull requests?*** + +***Does the website have a clear owner/maintainer?*** + +Review and approval of documentation releases is role-based and is controlled by +the OWNERS and OWNER_ALIASES files in the repo. A steering committee is among +the leadership identified in these files. + + +#### Inclusive language + +***Are there customer-facing utilities, endpoints, class names, or features*** +that use non-recommended words as documented by the Inclusive Naming +Initiative website? + +The documentation contains few non-recommended words as documented by the +[Inclusive Naming Initiative](https://inclusivenaming.org) website. + +***Does the project use language like "simple", "easy", etc.?*** + +The Knative documentation avoids ableist language. The Knative style guide +explicitly discourages language that assumes a level of understanding ("just", +"easily", "simply"). + +### Recommendations + +#### Organization + +The simplest solution to untangling the documentation from the landing page is +probably to: + +- Add a "Documentation" tab on the right alongside "Blog," "About," and +"Community" +- Move the tech docs items from the banner to the left-hand sidebar (LHS) + +Other suggestions: + +- Remove the "Home" item. +- Write a comprehensive "Concepts" section using conceptual material from the +rest of the documentation. +- Rename "Tutorial" to "Tutorials". +- Add navigational cues to the "Installation" section to better guide users to +the right instructions and downloads for their user role, OS, and use case. +- Rename "Developer Topics" and "Admin Topics" to "Developer Tasks" and "Admin + Tasks" to cue readers. These are effectively user guides and need to be + recognizable as such by users. +- Rename Eventing - "Knative Eventing - The Event-driven application platform + for Kubernetes". This is technical documentation. The marketing stuff goes + elsewhere. +- In the "Eventing" section, move "Event Mesh" under "Concepts". +- Rename "Knative CLI" to "CLI tools". Include the `kn` CLI documentation on the + documentation site. +- In "Reference": Rewrite at the top of the page: "This page describes Knative + security and disclosure information." + to + "This page describes how to validate code and report security vulnerabilites + in Knative. For a complete description of the Knative threat model, see the + [Knative security working group repo] + (https://github.com/knative/community/blob/main/working-groups/security/threat-model.md)." + Then change headings: "Verifying code signature" and "Reporting a + vulnerability." +- Move Release Notes out of Reference to be a top-level TOC item. +- Make the "Explore Knative" button the landing page link to the conceptual + overview. Or, change the button label to "Quick Start". +- Remove the Eventing FAQ. Its (single) response is documented elsewhere. +- Add a glossary in the Reference section. +- Reevaluate each graphic on the site. Is it adding value? If not, eliminate it. + Does it take up so much page space that it forces unnecessary scrolling? + Reduce the size. Especially in the E2E tutorial, get rid of the large graphics. + Their only purpose here is to cue the user to the type of task. Make them 32x32 + icons, or get rid of them. In the text, tell the user what the graphic is + before they see it, and make sure the picture is adding value, or else delete + it. +- Make TOC titles agree with page titles. Rename "About" in the banner to + something more descriptive: "Why Knative?", "Testimonials and Case Studies", + or "Endorsements". +- Revise to conform to the style guide: + - Rewrite "please" requests to straightforward instructions. For example: + "Please see XYZ" to "See XYZ". + - Remove "About" from headings. For example: "About the Prometheus Stack" to + "The Prometheus Stack". + - Spell out words to avoid abbreviations. For example: Replace "E2E" with "end + to end". + + +#### Information architecture + +***Conceptual overview*** + +Update the "Concepts" section to be a complete overview of the Knative system. +Start with an explanation of Knative's purpose that's understandable to new +users and to readers who are only passingly familiar with containerized software. + +Include a complete explanation of Knative's components and how they're related. +This is a good short explanation of the Knative components (though a little +marketing-ish) that's on the CNCF website: + + Knative is a developer-focused serverless application layer which is a great + complement to the existing Kubernetes application constructs. Knative consists + of three components: an HTTP-triggered autoscaling container runtime called + “Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called + “Knative Eventing”, and a developer-focused function framework which leverages + the Serving and Eventing components, called "Knative Functions". + +None of the instructional material is going to make sense without an +understanding of the Knative architecture. + +Some specifics: + +Rewrite: "The documentation in this section explains commonly referenced Knative +concepts and abstractions, and helps to provide you with a better understanding +of how Knative works." +as +"This documentation explains what Knative is for and how it works." + +***Escalation path*** + +Expand or eliminate the FAQ. My preference is to eliminate it. + +Organize the Troubleshooting procedures by symptom (within component). Or at +least expand the explanations in the Troubleshooting sections to describe what +each command is intended to diagnose. + +Expand the Eventing API reference to include meaningful explanations of every +field and function. Add a short introduction to the API reference. + +***New user content*** + +Add a "Getting Started" page at the top level of the documentation. This page +should map a reader's user role and goals to content that helps them install, +evaluate, or learn about the product, depending on their goal. For exmaple, +direct new users to the Quickstart tutorial, evaluators or potential buyers to +the conceptual overview, and so on. + +Currently a user who clicks in the install section to get an install file +download has to scroll through a lot of release notes before they reach the +downloads list. Move the install download links to the top of the Release Notes +or clearly link to them from the top of the Release Notes. Or, put them on their +own Downloads page. + +***Content maintainability & site mechanics*** + +Configure the Search to truncate results after 100 characters or so. Displaying +the entire page text of each result hinders users' ability to find their result. + +Address localization. If you have no intention to localize the documentation, +say so in the introduction. + +## Contributor documentation + +Knative is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | 5 - Exemplary | +| Beginner friendly issue backlog | 3 - Meets standards | +| “New contributor” getting started content | 3 - Meets standards | +| Project governance documentation | 4 - Meets or exceeds standards | + +### Comments + + +#### Communication methods documented + +***Is there a Slack/Discord or equivalent community linked from your website?*** + +***Is there a direct link to your GitHub project or repository?*** + +***Can users find and join periodic project meetings, if applicable?*** + +***Are mailing lists documented?*** + +The site lists community resources that include: + +- A number of general and subtopic-specific Slack channels +- A link to the Github doc repository +- An up-to-date published meeting schedule +- A Stack Overflow topic +- A Google Groups mailing list + + +#### Beginner friendly issue backlog + +***Are docs issues well-triaged?*** + +Doc issues are well triaged; there are tags classifying changes according to +size and status. + +***Is there a clearly marked way for new contributors to make contributions?*** +(A “good first issue” label?) + +There is a "good first issue" label in the issues list. + +***Are issues well-documented (i.e., more than just a title)?*** + +Issue descriptions are uneven. Many issues are well documented, but some lack +basic information. + +***Are issues maintained for staleness?*** + +There is a archiving bot for stale doc issues, but there are issues as old as +four years in the repo. + + +#### New contributor getting started content + +***Do you have a community repository or section on your website?*** + +There is a separate [community repo](https://github.com/knative/community) in +the Knative project. + +***Is there a document welcoming new contributors?*** +And documenting a first contribution process? + +There is ample documentation for contributors but no documentation specifically +for new contributors. + +***Can new users find where to get help?*** + +There are ample resources for new users to get support from the community. + + +#### Project governance documentation + +***Is project governance clearly documented?*** + +Project +[governance](https://github.com/knative/community/blob/main/GOVERNANCE.md) is +documented in the [community repo](https://github.com/knative/community) in the +Knative project. + + +### Recommendations + +No recommendations. + +#### Communication methods documented + +#### Beginner friendly issue backlog + +#### New contributor getting started content + +#### Project governance documentation + +## Website and infrastructure + +**TBD** + +Knative is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | [rating (1-5)] | +| Meets min website req. (for maturity level) | [rating (1-5)] | +| Usability, accessibility, and design | [rating (1-5)] | +| Branding and design | [rating (1-5)] | +| Case studies/social proof | [rating (1-5)] | +| SEO, Analytics, and site-local search | [rating (1-5)] | +| Maintenance planning | [rating (1-5)] | +| A11y plan & implementation | [rating (1-5)] | +| Mobile-first plan & impl. | [rating (1-5)] | +| HTTPS access & HTTP redirect | [rating (1-5)] | +| Google Analytics 4 for production only | [rating (1-5)] | +| Indexing allowed for production server only | [rating (1-5)] | +| Intra-site / local search | [rating (1-5)] | +| Account custodians are documented | [rating (1-5)] | + +### Comments + + +#### Single-source requirement + +The project website and documentaiton are contained in a single repo. + +Every code repo in the project has its own `docs` folder. + +#### Minimal website requirements + +Listed here are the minimal website requirements for projects based on their +[maturity level][maturity-level], either incubating or graduated. (These are the +only two levels for which a tech docs analysis can be requested.) + + + +| Criterion | Incubating Requirement | Graduated Requirement | +| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | +| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + + + +[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[maturity-level]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[cncf-servicedesk]: https://servicedesk.cncf.io + +#### Usability, accessibility and devices + +Most CNCF websites are accessed from mobile and other non-desktop devices at +least 10-20% of the time. Planning for this early in your website's design will +be much less effort than retrofitting a desktop-first design. + +- Is the website usable from mobile? +- Are doc pages readable? +- Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? +- Might a [mobile-first] design make sense for your project? + +[mobile-first]: + https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first + +Plan for suitable [accessibility][] measures for your website. For example: + +- Are color contrasts significant enough for color-impaired readers? +- Are most website features usable using a keyboard only? +- Does text-to-speech offer listeners a good experience? + +It is up to each project to set their own guidelines. + +[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility + +#### Branding and design + +CNCF seeks to support enterprise-ready open source software. A key aspect of +this is branding and marketing. + +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? + +Footer: "Knative is a Cloud Native Computing Foundation incubation project". Should be "incubating". + + +#### Case studies/social proof + +One of the best ways to advertise an open source project is to show other +organizations using it. + +We evaluate on the following: + +- Are there case studies available for the project and are they documented on + the website? +- Are there user testimonials available? +- Is there an active project blog? +- Are there community talks for the project and are they present on the website? +- Is there a logo wall of users/participating organizations? + +#### 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. + +We evaluate on the following: + +- Analytics: + - Is analytics enabled for the production server? + - Is analytics disabled for all other deploys? + - If your project used Google Analytics, have you migrated to GA4? + - Can Page-not-found (404) reports easily be generated from you site + analytics? Provide a sample of the site's current top-10 404s. +- Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches? +- Is local intra-site search available from the website? +- Are the current custodian(s) of the following accounts clearly documented: + analytics, Google Search Console, site-search (such as Google CSE or Algolia) + +#### Maintenance planning + +Website maintenance is an important part of project success, especially when +project maintainers aren’t web developers. + +We evaluate on the following: + +- Is your website tooling well supported by the community (i.e., Hugo with the + Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) +- Are you actively cultivating website maintainers from within the community? +- Are site build times reasonable? +- Do site maintainers have adequate permissions? + +#### Other + +- Is your website accessible via HTTPS? +- Does HTTP access, if any, redirect to HTTPS? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Single-source requirement + +#### Minimal website requirements + +#### Usability, accessibility and devices + +#### Branding and design + +#### Case studies/social proof + +#### SEO, Analytics and site-local search + +#### Maintenance planning + +#### Other + +#### References and notes + +##### Rating values + +The numeric rating values used in this document are as follows + +1. Not present +2. Needs improvement +3. Meets standards +4. Meets or exceeds standards +5. Exemplary + +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues]: ./issues.md +[project-doc-website]: https://knative.dev/docs/ +[project-website]: https://knative.dev/docs/ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md diff --git a/analyses/0015-knative/issues.md b/analyses/0015-knative/issues.md new file mode 100644 index 0000000..f7d5a71 --- /dev/null +++ b/analyses/0015-knative/issues.md @@ -0,0 +1,721 @@ +--- +title: Knative Issues +tags: Knative +created: 2025-07-28 +modified: 2025-07-28 +author: Dave Welsch (@dwelsch-esi) +--- + +# Separate technical documentation from the project page + +## Overview + +The Knative project [landing page] redirects to the doc page: +`https://knative.dev/docs/`. The project landing page contains all the +elements you'd expect on an open-source software page, including case studies, +user endorsements, and links to the community. + +It also includes the technical documentation in the banner menu. This +arrangement conflates the project and the technical documentation, mixing +marketing and technical information. + +It's helpful to users if there's a clear separation between technical +documentation and other information. The technical documentation is goal-driven +and should be factual, specific, and purposeful. + +The request: Separate the technical documentation from the project landing page. + +Audience: All + +Type: All + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/ +- https://github.com/knative/docs/ + + +Suggested changes: + +The simplest solution to untangling the documentation from the landing page is +probably to: + +- Reconfigure the site to use the base URL `https://knative.dev` as the project + landing page. +- Add a "Documentation" tab on the right alongside "Blog," "About," and + "Community" on the project page that links to the docs page, + `https://knative.dev/docs`. +- Move the tech docs items from the banner to the left-hand sidebar (LHS) on the + tech docs page. +- Remove the version drop-down from the project landing page (and the other + non-documentation project pages). + + +# Rename pages + +## Overview + +Well named pages and headings help users quickly find the right information. +Consistent naming aids in scanning the table of contents, and accurate names +make search more effective. + +Audit page and heading titles for consistency and accuracy. + +Audience: All + +Type: All + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/docs/ +- https://knative.dev/docs/client/ +- https://knative.dev/docs/getting-started/tutorial/ +- https://knative.dev/docs/serving/ +- https://knative.dev/docs/eventing/ + + +Suggested changes: + +- Remove "About" from titles: + - "About Installing Knative" > "Installing Knative" + - "About Eventing Features" > "Eventing Features" + - and so on. +- Rename "Tutorial" to "Tutorials" (there is more than one tutorial here). +- Make verb tense consistent in procedure titles. Use "-ing" verbs to title tasks + and processes (thiis is already done in the majority of cases!): + - [Configure Broker defaults] > "Configuring Broker defaults" + - [Install Knative using quickstart] > "Installing Knative using quickstart" + - and so on. +- In [Serving] and [Eventing], rename "Developer Topics" and + "Admin Topics" to "Developer Tasks" and "Admin Tasks" to cue readers. +- Retitle this page: + [Knative Eventing - The Event-driven application platform for Kubernetes] + to "Eventing". +- Rename "Knative CLI" to "CLI tools". +- Make TOC titles agree with page titles. Some examples (not a complete list): + - Change "Install the Knative CLI" in the TOC to match the page title: + [Installing the Knative CLI]. + - Change the page title: [Metrics] to match "Configuring metrics" in the TOC. + - Change "About Apache Kafka Broker" in the TOC to match the page title: + [Knative Broker for Apache Kafka]. +- Rename "About" in the landing page banner to something less misleading: "Why + Knative?", "Testimonials and Case Studies", or "Endorsements". + + +# Update technical overview + +## Overview + +Write a conceptual overview of Knative. This should go where the "Concepts" +section is in the current documentation, but be much more comprehensive. + +This conceptual overview serves two purposes: + +1. It helps potential users evaluate whether Knative is the right solution to +their problem; +2. It provides all users with enough background information to understand the +instructional and reference material later in the documentation. User don't have +to read it all before proceeding, but they will refer to it when they don't +understand how the product's pieces fit together. + +Audience: All + +Type: Conceptual + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + +## Possible Implementation + +Related material in the current doc: + +- https://knative.dev/docs/concepts/ +- https://knative.dev/docs/serving/ +- https://knative.dev/docs/serving/architecture/ +- https://knative.dev/docs/serving/request-flow/ +- Almost any page currently titled "About (something)" + + +Suggested changes: + +Update the "Concepts" page to be a comprehensive conceptual overview of the +entire system. Start with an introduction that explains what the product is +and what problems it is designed to solve. This information should be accessible +to someone who is not an expert container developer or admin. If some background +knowledge is required to understand the concepts, state what that knowledge is. + +Follow with a description of the product architecture that explains its +components and how they interoperate. From the CNCF website: + + Knative is a developer-focused serverless application layer which is a great + complement to the existing Kubernetes application constructs. Knative consists + of three components: an HTTP-triggered autoscaling container runtime called + “Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called + “Knative Eventing”, and a developer-focused function framework which leverages + the Serving and Eventing components, called "Knative Functions". + +Finally, explain essential but tangential topics like authenication and +authorization, still at a conceptual level. + +# Update Installation to better orient users + +## Overview + +The installation instructions are generally very good, but there are a few speed +bumps to finding and performing the right installation procedure. + +Add "roadmap" information to orient readers in the Installation section of the +documentation. + +Audience: Admins and developers + +Type: Instructional + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/install + + +Suggested changes: + +On the [Installing Knative] page, provide a roadmap at the top to direct users +to the correct installation. Aside from installing the different components +(Eventing and Serving) using different modalities (YAML, Kubernetes Operator, +and upgrading), disclose what operating systems are supported, and differentiate +between local and server installations. + +# Reorganization issues + +## Overview + +This issue suggests several changes to the documentation's organization to +improve usability and consistency. For example, several pages appear as +"orphans" (single subordinate headings) in the table of contents (TOC). This is +usually avoidable with better organization. + +Audience: All + +Type: All + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/eventing +- https://knative.dev/docs/eventing/event-mesh/ +- https://knative.dev/docs/reference/relnotes/ + +Suggested changes: + +- In the [Eventing] section, move "Event Mesh" under "Concepts". +- Move the [Release Notes] to the top level of the TOC + (and change the URL to https://knative.dev/docs/relnotes/). +- Make the "Explore Knative" button the landing page link to the conceptual + overview. Or, change the button label to "Quick Start". Its current label + is misleading. +- Remove the Eventing FAQ. It has only one entry, and that topic is covered + elsewhere in the documentation. +- Are [Revisions] the only Knative Resource? Roll this menu up: + `Serving > Resources > Revisions > About Revisions` + to `Serving > Revisions > About Revisions`. + +# Document the kn CLI on the site + +## Overview + +The `kn` CLI documentation is maintained in the +[/knative/kn] repo, except for the install instrutions, which are on the doc +site. + +Consolidate the `kn` CLI documentation so that it's maintained in one place. + +Audience: Admin and developer + +Type: Reference + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/ + + +Suggested changes: + +Document the `kn` CLI on the documentation website rather than linking to the +[/knative/kn] repo documentation. + + +# Revise the Security and threat disclosure page + +## Overview + +The +[Knative Security and Disclosure Information] page has some misleading and +confusing elements. Rewrite the introduction to this page so that it's clear +what procedures and information are available. + +Audience: Admin + +Type: Instructional + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://knative.dev/docs/reference/security/ + +Suggested changes: + +In [Reference]: + +Rewrite the introduction at the top of the page, including the bullet point link +to to the threat model, to: + +"This page describes how to validate code and report security vulnerabilites in +Knative. For a complete description of the Knative threat model, see the +[Knative security working group repo]." +Then change headings: "Verifying code signature" and "Reporting a vulnerability." + +Rename the heading "Code Signature Verification" to +"Verifying a code signature". + +Rename the heading "Report a vulnerability" to "Reporting a vulnerability". + +# Add a glossary + +## Overview + +A software product like Knative typically uses many terms specific to the +product and to its knowledge domain. Users, especially those new to the +software, need help making sense of these terms while reading the documentation. + +Add a glossary of terms to the technical documentation. + +Audience: All + +Type: Reference + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/ + + +Suggested changes: + +Add a glossary to the reference section of the documentation. Include terms that +are essential concepts in related software domains (containerization, server and +event architecture, etc.) as well as terms that are specific to Knative. A few +such terms: Custom resource, Eventing, func (CLI), kn (CLI), Operator, Serving, +Sink, Source, Webhook. + +A glossary entry should provide readers with a definition of the term, but not +try to explain it in detail. A sentence or two is usually enough. It's OK to +refer to other glossary entries in the definition. + +Order the entries alphabetically. + + +# Review graphics + +## Overview + +Graphics should enhance understanding by illustrating concepts and processes. +Many graphics on the Knative site detract from, rather than enhance, the +usability of documentation. + +Review the graphics on the site to make sure they meet these criteria: + +- Does the graphic enhance understanding? Does it add information that can't be + conveyed in a few words? +- Is the graphic placed in context by the surrounding text? +- Does the graphic's size and aspect ratio enable proper placement and text flow + on a variety of screens sizes? +- Is the graphic maintainable: Will it require frequent updating for + localization, software updates, or interface changes? + +Review the graphics that are on the site. Remove graphics that don't justify the +space they take up. Scale the graphics to a more appropriate size if necessary. + +Audience: All + +Type: Conceptual + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://knative.dev/docs/concepts/ +- https://knative.dev/docs/concepts/eventing-resources/brokers/ +- https://knative.dev/docs/getting-started/tutorial/ +- https://knative.dev/docs/getting-started/next-steps/ +- https://knative.dev/docs/bookstore/page-0/welcome-knative-bookstore-tutorial/ +- https://knative.dev/docs/bookstore/disclaimer/ +- https://knative.dev/docs/bookstore/* (all bookstore pages) +- https://knative.dev/docs/serving/architecture/ +- https://knative.dev/docs/serving/request-flow/ +- https://knative.dev/docs/serving/encryption/encryption-overview/ + + +Suggested changes: + +- Briefly introduce the system diagram in the [Concepts overview]. This can be a + single phrase added to the sentence below the graphic: "The primary Knative + Serving resources are Services, Routes, Configurations, and Revisions, as + shown in the previous figure:". +- Similarly for other conceptual graphics on the site: Refer to them from the + text. + + +# Edit for conformance to style guide + +## Overview + +Edit the website for conformance to the [Knative style guide]. + +Audience: All + +Type: All + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/ + + +Suggested changes: + +Specific Knative style rules that will have the biggest impact: +- *Use imperatives for headings of procedures.* Technical writing best practice + has traditionally been to use gerunds ("-ing" verbs), but this is okay as well. + More imporant is to be consistent. Use the same form for all procedure headings. +- *Use simple and direct language.* To the extent possible, follow the "Voice + and language" guidelines in the style guide. For example, there are 50 instances + of the word "please" in the Knative documentation. Remove these and use simple + imperative sentences for instructions. +- *Avoid statements that will soon be out of date.* This addresses + maintainability. See the [example] in the style guide. There are many instances + of the word "currently" in the Knative documentation. +- Spell out words to avoid abbreviations. For example: Replace "E2E" with "end + to end". +- *Use simple and direct language.* For example, from [Concepts]: "The + documentation in this section explains commonly referenced Knative concepts + and abstractions, and helps to provide you with a better understanding of how + Knative works" could be: "This documentation explains what Knative is for and + how it works." + + +# Improve troubleshooting + +## Overview + +Troubleshooting instructions are too terse in Knative. They provide commands for +diagnosing issues, but do not explain a procedure. + +Improve troubleshooting by adding explanations. + +Audience: All + +Type: Instructional + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://knative.dev/docs/install/troubleshooting/ +- https://knative.dev/docs/bookstore/page-0.5/environment-setup/#troubleshooting +- https://knative.dev/docs/install/installing-backstage-plugins/#troubleshooting +- https://knative.dev/docs/serving/troubleshooting/debugging-application-issues/ +- https://knative.dev/docs/bookstore/page-1/send-review-comment-to-broker/#step-2-create-broker +- https://knative.dev/docs/bookstore/page-2/sentiment-analysis-service-for-bookstore-reviews/#prerequisite-1-install-knative-func-cli + + +Suggested changes: + +Two possible approaches: + +1. Expand each troubleshooting step to explain what the step is trying to + diagnose. (Many of the current troubleshooting steps are no more than "use this + command to diagnose ..."). Make sure that there are links to each step from the + procedure where the issue can be encountered. +2. Consolidate all the troubleshooting procedures to a single troubleshooting + guide, organized by component. Again, provide links to the relevant points in + the guide from each procedure. + Exception: The end-to-end tutorial example has a lot of troubleshooting + information. As is the case currently, it should have its own troubleshooting + guide or guides. + +# Fill out the Eventing API + +## Overview + +The Eventing API contains no explanatory or introductory text, and many +descriptions of functions and fields are missing, rudimentary, or tautological. + +Improve the explanations in the Eventing API. + +Audience: Developers + +Type: Reference + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://knative.dev/docs/eventing/reference/eventing-api/ + + +Suggested changes: + +Add a brief introduction to the Eventing API, explaining what the API is for, +what kind of API it is (REST, presumably), where to find it, and how to include +it. + +Provide semantic information in descriptions about endpoints and fields. Do not +only restate information available from the element name. For example, the +`BackoffPolicyType` option has no explanation. It would be helpful to know what +the backoff is for: "Backoff is the delay before trying to reconnect after +failing to deliver an event" (or whatever). The description of its first value, +"exponential", reads: "Exponential backoff policy". More helpful would provide +more information: "Retry after an exponentially increasing number of seconds (1, +2, 4, 8, and so on)". + +# Write a Getting Started page + +The Quickstart tutorial is useful, but it doesn't fully orient new users. A +getting started page would help, with meta information about what to expect +and where to go on the documentation site. + +## Overview + +Audience: New users + +Type: Instructional + + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/ +- https://knative.dev/docs/getting-started/ + +Suggested changes: + +Add a "Getting Started" page at the top level of the documentation. This page +should map a reader's user role and goals to content that helps them install, +evaluate, or learn about the product, depending on their goal. For exmaple, +direct new users to the Quickstart tutorial, evaluators or potential buyers to +the conceptual overview, and so on. + +See, for example, getting started pages for: + +- [Kubernetes] +- [The Update Framework] + (a little unusual because it's a specification, not a software product) +- [Python] (a kitchen-sink approach, to be sure) + +# Make install downloads findable + +Currently the binary install download links in the Installing section redirect +to the release notes, where the list of download files is far down the page. +Move and relabel the download file sectionm so that the files are easy to find. + +## Overview + +Audience: All + +Type: Instructional + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://knative.dev/docs/install/quickstart-install/#__tabbed_1_2 +- https://knative.dev/docs/client/install-kn/#__tabbed_1_2 +- https://knative.dev/docs/install/operator/knative-with-operator-cli/#__tabbed_1_1 +- https://knative.dev/docs/install/operator/knative-with-operator-cli/#__tabbed_1_2 +- https://github.com/knative/client/releases + +Suggested changes: + +Move the install download links to the top of the Release Notes or clearly link +to them from the top of the Release Notes. Or, put them on their own Downloads +page. + +Rename the heading for the download files from "Assets" to "Downloads" or +"Install files". + +# Truncate search results + +## Overview + +Audience: All + +Type: All + +The Search function does not truncate results. For example, the "Puppet" entry +when searching "getting started" displays the page's entire 900 words. + +Configure the Search to truncate results after 100 characters or so. Displaying +the entire page text of each result hinders users' ability to find their result. + +## Context + +This issue tracks recommended changes resulting from an analysis of the Knative +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. + + +## Possible Implementation + +Related material in the current doc: + +- https://github.com/knative/ +- https://github.com/knative/docs/blob/main/mkdocs.yml + +Suggested changes: + +Search result entries are too long. The most straightforward solution is +probably to cut off each search result after a number of characters, say 100 or +so. + +This change probably has to be implemented in the `mkdocs` configuration. I'd +start by looking at the [mkdocs config file]. + + +[/knative/kn]: https://github.com/knative/client +[Concepts]: https://knative.dev/docs/concepts/ +[Concepts overview]: https://knative.dev/docs/concepts/ +[Configure Broker defaults]: https://knative.dev/docs/eventing/configuration/broker-configuration/ +[Eventing]: https://knative.dev/docs/eventing/ +[example]: https://github.com/knative/docs/blob/main/contribute-to-docs/style-guide/voice-and-language.md#avoid-statements-that-will-soon-be-out-of-date +[Install Knative using quickstart]: https://knative.dev/docs/install/quickstart-install/ +[Installing Knative]: https://github.com/knative/install +[Installing the Knative CLI]: https://knative.dev/docs/client/install-kn/ +[Knative Broker for Apache Kafka]: https://knative.dev/docs/eventing/brokers/broker-types/kafka-broker/ +[Knative Eventing - The Event-driven application platform for Kubernetes]: https://knative.dev/docs/eventing/ +[Knative Security and Disclosure Information]: https://knative.dev/docs/reference/security/ +[Knative security working group repo]: https://github.com/knative/community/blob/main/working-groups/security/threat-model.md +[Knative style guide]: https://github.com/knative/docs/tree/main/contribute-to-docs/style-guide +[Kubernetes]: https://kubernetes.io/docs/setup/ +[landing page]: https://knative.dev/ +[Metrics]: https://knative.dev/docs/serving/autoscaling/autoscaling-metrics/ +[mkdocs config file]: https://github.com/knative/docs/blob/main/mkdocs.yml +[Python]: https://wiki.python.org/moin/BeginnersGuide +[Reference]: https://knative.dev/docs/reference/ +[Release Notes]: https://knative.dev/docs/reference/relnotes/ +[Revisions]: https://knative.dev/docs/serving/revisions/ +[Serving]: https://knative.dev/docs/serving/ +[The Update Framework]: https://theupdateframework.io/docs/getting-started/ From 23edd703e234cf61d1229e9543539071e7eeb016 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Wed, 7 Jan 2026 18:41:10 +0000 Subject: [PATCH 024/104] chore: fix CI errors Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton --- .cspell.yml | 4 + analyses/0001-contour.md | 6 - analyses/0002-notary-project.md | 5 - analyses/0003-krator.md | 1 - analyses/0004-tremor.md | 11 - analyses/0005-fluxcd.md | 1 - analyses/0006-gateway-api.md | 2 - analyses/0007-porter.md | 2 - analyses/0008-backstage/backstage-analysis.md | 44 +-- .../backstage-implementation.md | 1 - analyses/0009-in-toto/in-toto-doc-issues.md | 2 - .../0009-in-toto/in-toto-implementation.md | 4 - .../0009-in-toto/survey-of-existing-doc.md | 1 - analyses/0012-TUF/implementation.md | 5 - analyses/0015-knative/analysis.md | 295 +++++++++--------- analyses/0015-knative/issues.md | 210 ++++++------- docs/analytics/ua-to-ga4.md | 8 - docs/website-guidelines-checklist.md | 4 +- 18 files changed, 258 insertions(+), 348 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 16e7762..c13d3e9 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -24,9 +24,12 @@ words: - CLOTributor - CNCF - Docsy + - dwelsch - keda + - knative - kedacore - krook + - mkdocs - nate - nvmrc - subpages @@ -34,3 +37,4 @@ words: - toolkits - toto - triaging + - Welsch diff --git a/analyses/0001-contour.md b/analyses/0001-contour.md index f5b0f1f..4c20b34 100644 --- a/analyses/0001-contour.md +++ b/analyses/0001-contour.md @@ -47,7 +47,6 @@ criterion’s definition. ### Comments - **Information Architecture**: - - Documentation is feature complete! - A clear "About" or "What is Contour?" page is missing. It partially exists on [Architecture](https://projectcontour.io/docs/v1.13.1/architecture) and @@ -83,7 +82,6 @@ criterion’s definition. - What's the next doc I should read _after_ this to understand Contour and how to customize it for my use case? - **Content maintainability**: - - Your documentation is searchable, which is great! - However, because there are docs on your site that live _outside_ of the docs directory, the entire site needs to be searchable. @@ -111,7 +109,6 @@ criterion’s definition. ### Recommendations - **Information Architecture**: - - The main issue with information architecture is titling. - **The guides section:** Having "Guides" as a top-level section which appears in the nav before documentation is a bit confusing. I recommend having @@ -139,7 +136,6 @@ criterion’s definition. a small win and a great first issue. - **New user content**: - - Work with a technical writer to revise your getting started page to provide a bit more background information about Contour for the true new learner and provide more "next steps" documentation. @@ -221,7 +217,6 @@ website, and in the repo. Great job team! - **Branding and design**: one extremely small styling suggestion which would make a great first issue: - - for `

` elements on documentation pages, change the margin from `margin-bottom: 2rem` to `margin-top: 1rem; margin-bottom: 1rem` or (preferred) `margin-top: 1.5rem; margin-bottom: 0.5rem;`. In general it's @@ -266,7 +261,6 @@ website, and in the repo. Great job team! The revised content could have the following structure, if desired: - Getting started guide: - - Introduction to Project Contour - Project philosophy - Why choose Contour over another (less opinionated) ingress controller diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md index bb1b7eb..bbadd5b 100644 --- a/analyses/0002-notary-project.md +++ b/analyses/0002-notary-project.md @@ -75,7 +75,6 @@ Criteria: - Is the documentation feature complete, as in each product feature is documented? - - As the project is in ongoing development, not every feature is completed and so there are some holes in the documentation. - The @@ -86,14 +85,12 @@ Criteria: - Are there step-by-step instructions (tasks, tutorials) documented for features? - - Since V2's documentation is so conceptual at this point (consisting mostly of specification), it may be best to leave it as is — linking to it directly during the development process, and planning documentation along side the development of the system as a whole. - Is the “happy path”/most common use case documented? - - The V1 Getting Started Guide is very good. Will V2 be able to draw from it? - If the documentation does not suffice, is there a clear escalation path for @@ -181,7 +178,6 @@ Criteria ### Comments & recommendations - Most of the issues in this section are a function of not having a website yet. - - As the website build process starts, put together a skeleton IA that can be filled in as the project grows. @@ -190,7 +186,6 @@ Criteria https://prometheus.io/community/. - There is no documentation for: - - Triaging docs issues - Clearly marking a way for new contributors to make code or documentation contributions (i.e. a “good first issue” label), and define what makes a diff --git a/analyses/0003-krator.md b/analyses/0003-krator.md index 9e6f5c6..5186a46 100644 --- a/analyses/0003-krator.md +++ b/analyses/0003-krator.md @@ -54,7 +54,6 @@ Criteria: ### Comments - **Information Architecture**: - - Documentation is currently in several locations and will need to be brought into one repo. The current resources are: - The project [README](https://github.com/krator-rs/krator) diff --git a/analyses/0004-tremor.md b/analyses/0004-tremor.md index 71500f9..53fd6fd 100644 --- a/analyses/0004-tremor.md +++ b/analyses/0004-tremor.md @@ -52,7 +52,6 @@ Scale: - **Information Architecture:** Project Tremor's documentation makes a number of individually small IA choices that culminate in a confusing experience for the user. - - The [Getting Started](https://www.tremor.rs/getting-started/) section covers a number of seemingly random topics, with some appearing to be focused on selling the project to new users (i.e. @@ -112,7 +111,6 @@ Scale: - **New user content:** Project Tremor has a Getting Started section but it's a little disorganized as mentioned above. This makes it difficult for an actual new user to understand. - - [Starting Tremor for the first time](https://www.tremor.rs/getting-started/starting/) is the best part of the getting started guide. However, it mentions that there are "many ways" to install Tremor - it would be good to point users to @@ -172,7 +170,6 @@ Scale: - **Get specific about your Getting Started:** Getting Started Guides contain a very predictable set of content: - - In one paragraph or less, what is this piece of software - What prerequisite software (i.e. Kubernetes) and knowledge (i.e., Go) do I need on my system to launch this? @@ -183,7 +180,6 @@ Scale: - **Reorganize the Operations section and retitle it "Using Tremor"**: Additionally, move some topics from the existing Getting Started section: - - [Configuring Tremor](https://docs.tremor.rs/operations/configuration-walkthrough/) - [Walkthrough: Configure a Tremor Deployment](https://docs.tremor.rs/operations/configuration-walkthrough/) - [Connectivity: Onramps and Offramps](https://www.tremor.rs/getting-started/connectivity/) @@ -207,7 +203,6 @@ Scale: - **Reorganize [Overview](https://docs.tremor.rs/overview/) with user-centeredness in mind**: I suggest creating a new section with the following content: - - The information on [The docs index](https://docs.tremor.rs/) as a page titled "Overview", with subpages: - [Architecture Overview](https://docs.tremor.rs/overview/) (note: you could @@ -218,7 +213,6 @@ Scale: - **Audit for colloquial/casual language, abbreviations, and other "basic" English:** - - This recommendation has less to do with casual language or abbreviations being _bad_, and more to do with the perception of professionalism for the project. @@ -269,7 +263,6 @@ Scale: and [issues for new users are tagged](https://github.com/tremor-rs/tremor-www-docs/issues?q=is%3Aissue+is%3Aclosed). Great work! - - One thing to note is when tagging an issue [as a good first issue](https://github.com/tremor-rs/tremor-www-docs/issues/101), assume the reader knows nothing and must be hand-held through the entire @@ -280,7 +273,6 @@ Scale: [Community](https://www.tremor.rs/community/) page exists but doesn't provide much guidance for new users. How do I get involved? When do community meetings happen? Where do I find the team on Discord or Slack? - - As mentioned above, [Development](https://docs.tremor.rs/development/) and [Governance](https://docs.tremor.rs/CodeOfConduct/) are targeted at contributor users and should be under the community section. @@ -296,7 +288,6 @@ Scale: - **Turn the Community page into a subsection and house Governance and Development documentation under it:** - - Specifically, move [Development](https://docs.tremor.rs/development/) to /community/development - Move @@ -325,7 +316,6 @@ Scale: **Comments** - **Branding and design:** - - On the whole, the Tremor docs site looks professional, if a little plain. - Because of the way the site deploys (from different repositories via GitHub pages), navigation is disjointed: if you're in the RFCs, you don't have the @@ -340,7 +330,6 @@ Scale: content you can showcase about the project? - **Case studies/social proof**: None available. - - Case studies/talks/generally showing that other projects use Tremor is one of the most powerful ways to gain new users. People love real-world examples of a codebase in action. diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md index e5f2675..d86bac6 100644 --- a/analyses/0005-fluxcd.md +++ b/analyses/0005-fluxcd.md @@ -89,7 +89,6 @@ Scale: high-level concepts better before beginning code: providing a bit more explanation up front, particularly around the object's required fields and what the expected values are. An example would be helpful for this audience. - - Items under the **Project** top level navigation section. At a glance I couldn't figure out how these were being pulled in via (I assume) the [Community repository](https://github.com/fluxcd/community), meaning they diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md index ed1433e..073165d 100644 --- a/analyses/0006-gateway-api.md +++ b/analyses/0006-gateway-api.md @@ -92,7 +92,6 @@ as well as where to find them. - The main task with information architecture is conceptualization and development as the documents are currently in different places. The following areas would establish a foundation: - - Introduction - Quick Start - Concepts @@ -270,7 +269,6 @@ The [website](https://gateway-api.sigs.k8s.io/) is accessible via HTTPS. [Copyright notices](https://github.com/cncf/foundation/blob/master/copyright-notices.md). - CNCF Branding elements - - “We are a Cloud Native Computing Foundation project.” or “We are a Cloud Native Computing Foundation sandbox project.” are present (depending on status) diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md index d9e3bf0..34bec4c 100644 --- a/analyses/0007-porter.md +++ b/analyses/0007-porter.md @@ -69,14 +69,12 @@ Scale: - There appear to be two different operator quick starts (or is it the difference between desired state and operator? maybe the operator one needs to be in Get Started) - - https://getporter.org/quickstart/desired-state/ - https://getporter.org/operator/quickstart/ - Mixins & Plugins sections duplicated in sidebar (and could potentially be organized under Concepts?) - Current info architecture - - root - Get started - Contribute diff --git a/analyses/0008-backstage/backstage-analysis.md b/analyses/0008-backstage/backstage-analysis.md index eee1d3c..281db93 100644 --- a/analyses/0008-backstage/backstage-analysis.md +++ b/analyses/0008-backstage/backstage-analysis.md @@ -118,11 +118,11 @@ such, and pertain to legal requirements such as copyright and licensing issues. | Criteria | 1 | 2 | 3 | 4 | 5 | | -------------------------- | --- | --- | --- | --- | --- | -| Information architecture | | ✔︎ | | | | -| New user content | | | | ✔︎ | | -| Content maintainability | | | ✔︎ | | | -| Content creation processes | | | ✔︎ | | | -| Inclusive language | | | | ✔︎ | | +| Information architecture | | ✔︎ | | | | +| New user content | | | | ✔︎ | | +| Content maintainability | | | ✔︎ | | | +| Content creation processes | | | ✔︎ | | | +| Inclusive language | | | | ✔︎ | | Scale: @@ -352,10 +352,10 @@ these navigation aids are adequate. | Criteria | 1 | 2 | 3 | 4 | 5 | | ----------------------------------------- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | ✔︎ | | -| Beginner friendly issue backlog | | | | ✔︎ | | -| “New contributor” getting started content | | | ✔︎ | | | -| Project governance documentation | | | | | ✔︎ | +| Communication methods documented | | | | ✔︎ | | +| Beginner friendly issue backlog | | | | ✔︎ | | +| “New contributor” getting started content | | | ✔︎ | | | +| Project governance documentation | | | | | ✔︎ | Scale: @@ -423,19 +423,19 @@ from the product documentation. | Criteria | 1 | 2 | 3 | 4 | 5 | | ------------------------------------------- | --- | --- | --- | --- | --- | -| Single source for all files | | | ✔︎ | | | -| Meets min website req. (for maturity level) | | ✔︎ | | | | -| Branding and design | | | | ✔︎ | | -| Case studies/social proof | | | ✔︎ | | | -| SEO, Analytics, and site-local search | | | | | ✔︎ | -| Maintenance planning | | | ✔︎ | | | -| A11y plan & implementation | | | | ✔︎ | | -| Mobile-first plan & impl. | | | ✔︎ | | | -| HTTPS access & HTTP redirect | | | | | ✔︎ | -| Google Analytics 4 for production only | | | | | ✔︎ | -| Indexing allowed for production server only | | | | | ✔︎ | -| Intra-site / local search | | | | | ✔︎ | -| Account custodians are documented | ✔︎ | | | | | +| Single source for all files | | | ✔︎ | | | +| Meets min website req. (for maturity level) | | ✔︎ | | | | +| Branding and design | | | | ✔︎ | | +| Case studies/social proof | | | ✔︎ | | | +| SEO, Analytics, and site-local search | | | | | ✔︎ | +| Maintenance planning | | | ✔︎ | | | +| A11y plan & implementation | | | | ✔︎ | | +| Mobile-first plan & impl. | | | ✔︎ | | | +| HTTPS access & HTTP redirect | | | | | ✔︎ | +| Google Analytics 4 for production only | | | | | ✔︎ | +| Indexing allowed for production server only | | | | | ✔︎ | +| Intra-site / local search | | | | | ✔︎ | +| Account custodians are documented | ✔︎ | | | | | Scale: diff --git a/analyses/0008-backstage/backstage-implementation.md b/analyses/0008-backstage/backstage-implementation.md index 0668d23..2bb9916 100644 --- a/analyses/0008-backstage/backstage-implementation.md +++ b/analyses/0008-backstage/backstage-implementation.md @@ -153,7 +153,6 @@ The following artifacts should be written and made findable for developers. 1. A getting started guide for developers. Provide a clear work path that describes how to: - 1. Download and install any necessary software components 1. Integrate Backstage with an existing development environment diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md index fdc94a0..29f61b9 100644 --- a/analyses/0009-in-toto/in-toto-doc-issues.md +++ b/analyses/0009-in-toto/in-toto-doc-issues.md @@ -21,7 +21,6 @@ repurposed as the new overall **Doc home page**. This is a necessary step in raising the maturity level of this project. The roadmap should initially describe and provide access to: - - Specification - Basic demo - Python reference implementation along with its reference docs (which need to @@ -40,7 +39,6 @@ repurposed as the new overall **Doc home page**. - [ ] Move the content of the [README for the main repo](https://github.com/in-toto/in-toto) to a separate **"Getting Started" document**. - - [ ] Add a prominent pointer to the new **"Getting Started" document** on the in-toto home page, such as the top menu item in the "Get Started" menu. - [ ] Replace the README with brief introductory notes that link to the diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md index 68f15f0..06ac4f3 100644 --- a/analyses/0009-in-toto/in-toto-implementation.md +++ b/analyses/0009-in-toto/in-toto-implementation.md @@ -88,7 +88,6 @@ following general plan. d. Expose parts of the product specification as separate named documents on the website, as: - - [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) (compare content to https://in-toto.io/in-toto and current website About - create versions of increasing depth to address to specific audiences) @@ -159,7 +158,6 @@ following general plan. 2.3 Move important sections out of the spec into separate documents, and add them to the Doc home-page TOC. - - Evaluate the depth of the [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) and decide which user population it is most suitable for, or adapt it to @@ -229,7 +227,6 @@ following general plan. 5.2 Publish the policy and procedures for developers to document their implementations. - - Develop a documentation policy for implementers. For example, the auto-generated doc for the [Go implementation](https://pkg.go.dev/github.com/in-toto/in-toto-golang) @@ -252,7 +249,6 @@ following general plan. the project doc repo. 6.3 Make sure the policy pages include or link to: - - Contact info for maintainer/reviewer for documentation contributions. - Available doc style guides/templates (as well as code standards) - Usage guidelines for RTD (or other doc tool) and any project-specific usage diff --git a/analyses/0009-in-toto/survey-of-existing-doc.md b/analyses/0009-in-toto/survey-of-existing-doc.md index b9903c8..5405ccc 100644 --- a/analyses/0009-in-toto/survey-of-existing-doc.md +++ b/analyses/0009-in-toto/survey-of-existing-doc.md @@ -33,7 +33,6 @@ https://github.com/in-toto/attestation https://github.com/in-toto/demo - Doc generation repo: https://github.com/in-toto/docs - - Generated (read-the-docs) for Python reference implementation - Installation https://in-toto.readthedocs.io/en/latest/installing.html diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index e83c670..fb21cfa 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -27,7 +27,6 @@ pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: - **Reorganize documentation** - - Introduce a docs section and place some sections like **Getting started** under it to avoid repetition - Structure 'Getting started' according to user roles @@ -35,7 +34,6 @@ The top-level documentation recommendations for this project are: easier to find. - **Introduce instructional documentation** - - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - Develop quick start and contribution guides for new users @@ -65,7 +63,6 @@ structure: - **Home page** - **Documentation**: Overview of TUF - - Overview: Metadata,Project,Security - Getting started: Adopters, contributors, - History @@ -74,7 +71,6 @@ structure: - FAQ - **Community**: You can have two sections. - - Learn and connect: Includes all community communication channels including social media, mailing lists, calendars, Slack, etc. - Develop and Contribute: Information about how to contribute to TUF @@ -102,7 +98,6 @@ Contributors: - **Adopters**: Integrate TUF security properties into new and existing content delivery systems. Adopters can be classified into two categories: - - _Client maintainers_: depend on repository maintainers, to provide a TUF repo. And they can choose from multiple TUF client implementations (python-tuf, go-tuf, etc.) Typically, they will pick the language their diff --git a/analyses/0015-knative/analysis.md b/analyses/0015-knative/analysis.md index e985156..43d3e02 100644 --- a/analyses/0015-knative/analysis.md +++ b/analyses/0015-knative/analysis.md @@ -6,7 +6,7 @@ modified: 2025-07-25 author: Dave Welsch (@dwelsch-esi) --- - + ## Introduction @@ -22,12 +22,11 @@ efforts. ### Purpose -This document was written to analyze the current state of Knative -documentation. It aims to provide project leaders with an informed understanding -of potential problems in current project documentation. A second -document is a list of [issues] to be added to the project -documentation repository. These issues can be taken up by contributors to -improve the documentation. +This document was written to analyze the current state of Knative documentation. +It aims to provide project leaders with an informed understanding of potential +problems in current project documentation. A second document is a list of +[issues] to be added to the project documentation repository. These issues can +be taken up by contributors to improve the documentation. This document: @@ -42,8 +41,8 @@ the technical documentation, and documentation for contributors and users on the Knative GitHub repository. The Knative website and documentation are written in Markdown and are compiled -using the mkdocs static site generator with the Material theme. -The site's code is stored on the knative/docs GitHub repo. +using the mkdocs static site generator with the Material theme. The site's code +is stored on the knative/docs GitHub repo. #### In scope @@ -84,8 +83,8 @@ Each section begins with summary ratings based on a rubric with appropriate - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. -The accompanying [issues] document contains actionable improvements -for inclusion in [project-doc-website]/issues. +The accompanying [issues] document contains actionable improvements for +inclusion in [project-doc-website]/issues. ### How to use this document @@ -121,7 +120,7 @@ Knative is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. | Criterion | [Rating (1-5)] | -| -------------------------- | -------------- | +| -------------------------- | --------------------- | | Information architecture | 2 - Needs improvement | | New user content | 2 - Needs improvement | | Content maintainability | 3 - Meets standards | @@ -136,23 +135,23 @@ around organization and the new user experience. Following are general comments that don't address specific CNCF criteria. The project main landing page also serves as the documentation landing page, -mixing marketing and technical information. It's helpful to users if there's -a clear separation between technical documentation and other information. -The technical documentation is goal-driven and should be factual, specific, -and purposeful. +mixing marketing and technical information. It's helpful to users if there's a +clear separation between technical documentation and other information. The +technical documentation is goal-driven and should be factual, specific, and +purposeful. The technical documentation outline in the banner headings is good from a organizational perspective: Concepts, Tutorial, and Installing, then instructional information, then reference information. See notes below on the Left-hand sidebar (LHS) table of contents. Some other notes: -- The "Home" item is unnecessary for the project landing page. By convention -the upper-left logo links to the site landing page. -- The "Concepts" section is a brief introduction. Instead, it should contain -a complete technical overview that's accessible to a new user. +- The "Home" item is unnecessary for the project landing page. By convention the + upper-left logo links to the site landing page. +- The "Concepts" section is a brief introduction. Instead, it should contain a + complete technical overview that's accessible to a new user. - "Installing" does a good job of providing complete installation instructions -for all user roles. Some additional "road signs" would help to guide users to -the correct installation for their role, OS, and so on. + for all user roles. Some additional "road signs" would help to guide users to + the correct installation for their role, OS, and so on. - "Serving" and "Eventing" organize the instructional information by functional component, and by user role within the component. The alternative is to flip this and organize by user role first: @@ -161,7 +160,7 @@ the correct installation for their role, OS, and so on. - Serving - Developer Guide - Eventing - - Serviing + - Serving - Knative CLI - The title implies a dedicated Knative CLI. There are two Knative CLIs documented here, `kn` and `func`. As well, `kubectl` is the first CLI documented on the page. @@ -171,46 +170,46 @@ The reference to the repo-based documentation is OK, but why is the not documented here? Its installation is documented on the site; this seems inconsistent. -***Table of contents*** +**_Table of contents_** The table of contents (TOC) in the LHS is hard to navigate. Some issues: 1. The LHS contains only one technical documentation section at a time (see - previous comment about the banner menu). It's more usual for the LHS to - contain the entire TOC and to not change between pages (except for expanding - and collapsing headings). -2. The expand/collapse items in the TOC are navigational only; they do not - bring up information pages. This isn't uncommon, but it's tedious to navigate - multi-level topics. It's also less efficient than displaying the overview or - introduction with the top-level entry. -3. There are singleton sub-headings in the TOC. For example, see [Concepts > - Resources > Serving Resources > Revisions] - (https://knative.dev/development/concepts/serving-resources/revisions/). - Especially with the navigation-only expand/collapse items, these represent - extra mouse clicks for the user with no added benefit. -4. There are multiple entry points to the same documentation in the TOC. *And* - there are duplicate information sections. For example: - Installing > Install the Knative CLI sends you to the `Knative CLI` page. This - completely changes the left-hand TOC but the banner menu is not set up to - highlight `Knative CLI`, so are no cues as to where you were just teleported - (violating the [principle of least astonishment] - (https://en.wikipedia.org/wiki/Principle_of_least_astonishment)). - -***New user experience*** + previous comment about the banner menu). It's more usual for the LHS to + contain the entire TOC and to not change between pages (except for expanding + and collapsing headings). +2. The expand/collapse items in the TOC are navigational only; they do not + bring up information pages. This isn't uncommon, but it's tedious to + navigate multi-level topics. It's also less efficient than displaying the + overview or introduction with the top-level entry. +3. There are singleton sub-headings in the TOC. For example, see [Concepts > + Resources > Serving Resources > Revisions] + (https://knative.dev/development/concepts/serving-resources/revisions/). + Especially with the navigation-only expand/collapse items, these represent + extra mouse clicks for the user with no added benefit. +4. There are multiple entry points to the same documentation in the TOC. _And_ + there are duplicate information sections. For example: Installing > Install + the Knative CLI sends you to the `Knative CLI` page. This completely changes + the left-hand TOC but the banner menu is not set up to highlight + `Knative CLI`, so are no cues as to where you were just teleported + (violating the [principle of least astonishment] + (https://en.wikipedia.org/wiki/Principle_of_least_astonishment)). + +**_New user experience_** The blurb under "Need to know more?" on the landing page sounds like it's going -to an information resource; the button says "Explore Knative". Instead it -goes to the Quickstart tutorials. It sounds more like it should go to "Serving +to an information resource; the button says "Explore Knative". Instead it goes +to the Quickstart tutorials. It sounds more like it should go to "Serving Architecture". -***Graphics*** +**_Graphics_** In many places, large graphics are placed before any explanatory text. Also, many graphics, especially in the E2E tutorial (incidentally, "end-to-end" should be spelled out), provide no information but serve to distract, clutter, and take up valuable screen space. -***Headings and titles*** +**_Headings and titles_** Tasks are for the most part well named using appropriate verbs. @@ -221,9 +220,9 @@ Project Documentation. #### Information architecture -***Is there high level conceptual content?*** +**_Is there high level conceptual content?_** -The "Concepts" document at the top of the websiteis a brief introduction to two +The "Concepts" document at the top of the website is a brief introduction to two of the components of Knative. It does not introduce the overall architecture or explain how it works. @@ -232,7 +231,7 @@ throughout the website. The existing conceptual information seems to assume that you're already familiar with Kubernetes and with the problems that Knative is intended to solve. -***Is every product feature documented?*** +**_Is every product feature documented?_** The documentation seems a little behind being feature-complete, based on open Github issues requesting feature documentation. See for example issues @@ -242,52 +241,53 @@ Github issues requesting feature documentation. See for example issues Every component section (Eventing, Serving) is organized differently. This requires extra cognitive work from the readers. -***Does the documentation define all user roles (personas) for the product?*** +**_Does the documentation define all user roles (personas) for the product?_** The "Audiences information" in Community is a good description of user roles. This information is reflected in subsections of the "Eventing" and "Serving" sections in the division between Developer and Admin topics. -***Are there instructions (tasks, tutorials) documented for features?*** +**_Are there instructions (tasks, tutorials) documented for features?_** Tasks are documented for most features. -***Are there instructions for all major use cases for each user role?*** +**_Are there instructions for all major use cases for each user role?_** Tasks are covered for different user roles; it's unknown whether this coverage is complete. -***Are tasks organized by user role and use case?*** +**_Are tasks organized by user role and use case?_** The documentation is organized by the key components. Tasks for each component -seem to be present, but could be more clearly written and better labeleled. +seem to be present, but could be more clearly written and better labeled. -***Does instructional content demonstrate atomicity*** -Are individual tasks clearly named according to their goals? +**_Does instructional content demonstrate atomicity_** Are individual tasks +clearly named according to their goals? For the most part tasks seem separate and well named. -***Are tasks written as numbered step-by-step instructions?*** +**_Are tasks written as numbered step-by-step instructions?_** Tasks are broken down into steps. In most cases steps are not numbered. Some procedures have embedded subtasks. Numbering of tasks and subtasks is inconsistent. -***Are task descriptions in headings and the TOC described with a verb phrase?*** +**_Are task descriptions in headings and the TOC described with a verb +phrase?_** Most task headings accurately describe the task. -***Is the documentation free of features that lack task documentation?*** +**_Is the documentation free of features that lack task documentation?_** Task documentation seems to exist for key features. It is sometimes difficult to locate. -***Is the “happy path” — the most common use case — documented?*** +**_Is the “happy path” — the most common use case — documented?_** The "Happy Path" seems to be building and running a simple service using all three of the Knative components. This is documented in the "E2E" tutorial. -***Is there a clear escalation path for users needing more help?*** +**_Is there a clear escalation path for users needing more help?_** In general, Knative help and community support are strong throughout the documentation and repositories. Troubleshooting could provide clearer @@ -302,42 +302,41 @@ documentation. The troubleshooting steps are little more than command examples showing the non-exception case output. In some cases the output is cryptic and it's not clear what to do. -***If the product exposes an API, is there a complete reference?*** +**_If the product exposes an API, is there a complete reference?_** There is a reference for the Eventing API. It contains no explanatory or introductory text, and many descriptions of functions and fields are missing, rudimentary, or tautological. -***If the product has CLIs, are there complete references?*** +**_If the product has CLIs, are there complete references?_** There are references for the two CLIs, `kn` and `func`. The references are contained in their respective repos, not in the technical documentation. -***Is content up to date and accurate?*** +**_Is content up to date and accurate?_** The content seems up to date based on the versioning and release mechanisms. -***Does the doc separate conceptual, instructional, and reference info?*** +**_Does the doc separate conceptual, instructional, and reference info?_** Individual topics are separated by information type. - #### New user content -***Is “getting started” clearly labeled?** -(“Getting started”, “Installation”, “First steps”, or the equivalent.) +**\*Is “getting started” clearly labeled?** (“Getting started”, “Installation”, +“First steps”, or the equivalent.) -There is no clearly labeleld "Getting Started" page. There is a "Quickstart" +There is no clearly labeled "Getting Started" page. There is a "Quickstart" tutorial, with an accompanying plugin, that serves (primarily) as a beginner getting-started procedure. -***Is there a “getting started” path for all user roles?*** +**_Is there a “getting started” path for all user roles?_** -The "Quckstart" tutorial does not discuss roles. It acknowledges that the +The "Quickstart" tutorial does not discuss roles. It acknowledges that the exercise does a simplified local installation and directs the reader to YAML or Operator-based installs for production server installation. -***Is installation documented step-by-step?*** +**_Is installation documented step-by-step?_** Installation is thoroughly documented. Instructions are step-by-step and well organized. That said, I could not install using the Quickstart tutorial because @@ -346,107 +345,104 @@ Release Notes pages for binary downloads. This was confusing. Downloading the binary from the release page is not straightforward. The download links are under "Assets", far down the page. -***Are different types of installation documented if necessary?*** -(development, test, production) +**_Are different types of installation documented if necessary?_** (development, +test, production) The Quickstart tutorial documents a local install. Other (server) installs are documented in the Install section. -***If needed, are multiple OSes documented?*** +**_If needed, are multiple OSes documented?_** Installs for multiple OSes are documented implicitly (for example, the install binaries are characteristic of their respective OSes). A discussion of OSes up -front in the prereqs section would be appropriate. +front in the prerequisite section would be appropriate. -***Do users know where to go after reading the getting started guide?*** +**_Do users know where to go after reading the getting started guide?_** Next steps are documented at the end of the quickstart and some other sections. -***Is new user content clearly signposted on the site’s homepage?*** +**_Is new user content clearly signposted on the site’s homepage?_** There is no clearly labeled new user content available from the landing page. The closest is the Quickstart tutorial. -***Is there easily copy-pastable sample code or other example content?*** +**_Is there easily copy-paste sample code or other example content?_** There are code samples available in "Code samples", organized by Knative component. #### Content maintainability and site mechanics - -***Is your documentation searchable?*** +**_Is your documentation searchable?_** The documentation is searchable. The Search function does not truncate results. For example, the "Puppet" entry when searching "getting started" displays the page's entire 900 words. -***Are you planning for localization/internationalization?*** +**_Are you planning for localization/internationalization?_** -***Is a localization framework present?*** +**_Is a localization framework present?_** Apparently not. There is no evident localization or mechanism for localization. -***Do you have a clearly documented method for versioning your content?*** +**_Do you have a clearly documented method for versioning your content?_** Content is versioned up to the most recent release using branches in the knative/docs Github repo. The process is documented in the contribute-to-docs directory in the repo. The version drop-down contains the latest three releases plus pre-release. No older archived versions are offered on the site. -***Is release-specific information documented in release notes?*** +**_Is release-specific information documented in release notes?_** The repo contains appropriate release notes. -***Is the documentation free of duplicate sections of information?*** +**_Is the documentation free of duplicate sections of information?_** Duplicated information is present in the doc. It is deliberately included from a collection of reusable doc snippets. -***Do informational graphics add value by providing information?*** +**_Do informational graphics add value by providing information?_** Graphics are large and contain little new information, especially in the E2E tutorial. Some of the conceptual diagrams (component diagrams, flow charts) are helpful. -***Will graphics require modifications?*** -For example, due to software changes, GUI updates, or translation? +**_Will graphics require modifications?_** For example, due to software changes, +GUI updates, or translation? Graphics are unlikely to require frequent updates; for example, there are no screen shots. - #### Content creation processes -***Is there a clearly documented contribution process for documentation?*** +**_Is there a clearly documented contribution process for documentation?_** The documentation contribution process is well documented in the repo. -***Does the code release process include documentation creation & updates?*** +**_Does the code release process include documentation creation & updates?_** Documentation releases are controlled by the release process. The contribution process documents how to update previous versions of the documentation, if necessary. -***Who reviews and approves documentation pull requests?*** +**_Who reviews and approves documentation pull requests?_** -***Does the website have a clear owner/maintainer?*** +**_Does the website have a clear owner/maintainer?_** Review and approval of documentation releases is role-based and is controlled by the OWNERS and OWNER_ALIASES files in the repo. A steering committee is among the leadership identified in these files. - #### Inclusive language -***Are there customer-facing utilities, endpoints, class names, or features*** -that use non-recommended words as documented by the Inclusive Naming -Initiative website? +**_Are there customer-facing utilities, endpoints, class names, or features_** +that use non-recommended words as documented by the Inclusive Naming Initiative +website? The documentation contains few non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website. -***Does the project use language like "simple", "easy", etc.?*** +**_Does the project use language like "simple", "easy", etc.?_** The Knative documentation avoids ableist language. The Knative style guide explicitly discourages language that assumes a level of understanding ("just", @@ -460,17 +456,17 @@ The simplest solution to untangling the documentation from the landing page is probably to: - Add a "Documentation" tab on the right alongside "Blog," "About," and -"Community" + "Community" - Move the tech docs items from the banner to the left-hand sidebar (LHS) Other suggestions: - Remove the "Home" item. - Write a comprehensive "Concepts" section using conceptual material from the -rest of the documentation. + rest of the documentation. - Rename "Tutorial" to "Tutorials". - Add navigational cues to the "Installation" section to better guide users to -the right instructions and downloads for their user role, OS, and use case. + the right instructions and downloads for their user role, OS, and use case. - Rename "Developer Topics" and "Admin Topics" to "Developer Tasks" and "Admin Tasks" to cue readers. These are effectively user guides and need to be recognizable as such by users. @@ -481,11 +477,9 @@ the right instructions and downloads for their user role, OS, and use case. - Rename "Knative CLI" to "CLI tools". Include the `kn` CLI documentation on the documentation site. - In "Reference": Rewrite at the top of the page: "This page describes Knative - security and disclosure information." - to - "This page describes how to validate code and report security vulnerabilites - in Knative. For a complete description of the Knative threat model, see the - [Knative security working group repo] + security and disclosure information." to "This page describes how to validate + code and report security vulnerabilities in Knative. For a complete description + of the Knative threat model, see the [Knative security working group repo] (https://github.com/knative/community/blob/main/working-groups/security/threat-model.md)." Then change headings: "Verifying code signature" and "Reporting a vulnerability." @@ -496,11 +490,11 @@ the right instructions and downloads for their user role, OS, and use case. - Add a glossary in the Reference section. - Reevaluate each graphic on the site. Is it adding value? If not, eliminate it. Does it take up so much page space that it forces unnecessary scrolling? - Reduce the size. Especially in the E2E tutorial, get rid of the large graphics. - Their only purpose here is to cue the user to the type of task. Make them 32x32 - icons, or get rid of them. In the text, tell the user what the graphic is - before they see it, and make sure the picture is adding value, or else delete - it. + Reduce the size. Especially in the E2E tutorial, get rid of the large + graphics. Their only purpose here is to cue the user to the type of task. Make + them 32x32 icons, or get rid of them. In the text, tell the user what the + graphic is before they see it, and make sure the picture is adding value, or + else delete it. - Make TOC titles agree with page titles. Rename "About" in the banner to something more descriptive: "Why Knative?", "Testimonials and Case Studies", or "Endorsements". @@ -512,25 +506,25 @@ the right instructions and downloads for their user role, OS, and use case. - Spell out words to avoid abbreviations. For example: Replace "E2E" with "end to end". - #### Information architecture -***Conceptual overview*** +**_Conceptual overview_** Update the "Concepts" section to be a complete overview of the Knative system. Start with an explanation of Knative's purpose that's understandable to new -users and to readers who are only passingly familiar with containerized software. +users and to readers who are only passingly familiar with containerized +software. Include a complete explanation of Knative's components and how they're related. This is a good short explanation of the Knative components (though a little marketing-ish) that's on the CNCF website: - Knative is a developer-focused serverless application layer which is a great - complement to the existing Kubernetes application constructs. Knative consists - of three components: an HTTP-triggered autoscaling container runtime called - “Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called - “Knative Eventing”, and a developer-focused function framework which leverages - the Serving and Eventing components, called "Knative Functions". +Knative is a developer-focused serverless application layer which is a great +complement to the existing Kubernetes application constructs. Knative consists +of three components: an HTTP-triggered autoscaling container runtime called +“Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called +“Knative Eventing”, and a developer-focused function framework which leverages +the Serving and Eventing components, called "Knative Functions". None of the instructional material is going to make sense without an understanding of the Knative architecture. @@ -539,11 +533,10 @@ Some specifics: Rewrite: "The documentation in this section explains commonly referenced Knative concepts and abstractions, and helps to provide you with a better understanding -of how Knative works." -as -"This documentation explains what Knative is for and how it works." +of how Knative works." as "This documentation explains what Knative is for and +how it works." -***Escalation path*** +**_Escalation path_** Expand or eliminate the FAQ. My preference is to eliminate it. @@ -554,11 +547,11 @@ each command is intended to diagnose. Expand the Eventing API reference to include meaningful explanations of every field and function. Add a short introduction to the API reference. -***New user content*** +**_New user content_** Add a "Getting Started" page at the top level of the documentation. This page should map a reader's user role and goals to content that helps them install, -evaluate, or learn about the product, depending on their goal. For exmaple, +evaluate, or learn about the product, depending on their goal. For example, direct new users to the Quickstart tutorial, evaluators or potential buyers to the conceptual overview, and so on. @@ -568,7 +561,7 @@ downloads list. Move the install download links to the top of the Release Notes or clearly link to them from the top of the Release Notes. Or, put them on their own Downloads page. -***Content maintainability & site mechanics*** +**_Content maintainability & site mechanics_** Configure the Search to truncate results after 100 characters or so. Displaying the entire page text of each result hinders users' ability to find their result. @@ -582,7 +575,7 @@ Knative is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. | Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | +| ----------------------------------------- | ------------------------------ | | Communication methods documented | 5 - Exemplary | | Beginner friendly issue backlog | 3 - Meets standards | | “New contributor” getting started content | 3 - Meets standards | @@ -590,16 +583,15 @@ have [_very high_][criteria] standards for documentation. ### Comments - #### Communication methods documented -***Is there a Slack/Discord or equivalent community linked from your website?*** +**_Is there a Slack/Discord or equivalent community linked from your website?_** -***Is there a direct link to your GitHub project or repository?*** +**_Is there a direct link to your GitHub project or repository?_** -***Can users find and join periodic project meetings, if applicable?*** +**_Can users find and join periodic project meetings, if applicable?_** -***Are mailing lists documented?*** +**_Are mailing lists documented?_** The site lists community resources that include: @@ -609,58 +601,54 @@ The site lists community resources that include: - A Stack Overflow topic - A Google Groups mailing list - #### Beginner friendly issue backlog -***Are docs issues well-triaged?*** +**_Are docs issues well-triaged?_** Doc issues are well triaged; there are tags classifying changes according to size and status. -***Is there a clearly marked way for new contributors to make contributions?*** +**_Is there a clearly marked way for new contributors to make contributions?_** (A “good first issue” label?) There is a "good first issue" label in the issues list. -***Are issues well-documented (i.e., more than just a title)?*** +**_Are issues well-documented (i.e., more than just a title)?_** Issue descriptions are uneven. Many issues are well documented, but some lack basic information. -***Are issues maintained for staleness?*** +**_Are issues maintained for staleness?_** There is a archiving bot for stale doc issues, but there are issues as old as four years in the repo. - #### New contributor getting started content -***Do you have a community repository or section on your website?*** +**_Do you have a community repository or section on your website?_** There is a separate [community repo](https://github.com/knative/community) in the Knative project. -***Is there a document welcoming new contributors?*** -And documenting a first contribution process? +**_Is there a document welcoming new contributors?_** And documenting a first +contribution process? There is ample documentation for contributors but no documentation specifically for new contributors. -***Can new users find where to get help?*** +**_Can new users find where to get help?_** There are ample resources for new users to get support from the community. - #### Project governance documentation -***Is project governance clearly documented?*** +**_Is project governance clearly documented?_** Project [governance](https://github.com/knative/community/blob/main/GOVERNANCE.md) is documented in the [community repo](https://github.com/knative/community) in the Knative project. - ### Recommendations No recommendations. @@ -699,10 +687,9 @@ have [_very high_][criteria] standards for documentation. ### Comments - #### Single-source requirement -The project website and documentaiton are contained in a single repo. +The project website and documentation are contained in a single repo. Every code repo in the project has its own `docs` folder. @@ -766,8 +753,8 @@ We evaluate on the following: - Is the brand used across the website consistently? - Is the website’s typography clean and well-suited for reading? -Footer: "Knative is a Cloud Native Computing Foundation incubation project". Should be "incubating". - +Footer: "Knative is a Cloud Native Computing Foundation incubation project". +Should be "incubating". #### Case studies/social proof diff --git a/analyses/0015-knative/issues.md b/analyses/0015-knative/issues.md index f7d5a71..9a314f1 100644 --- a/analyses/0015-knative/issues.md +++ b/analyses/0015-knative/issues.md @@ -6,18 +6,20 @@ modified: 2025-07-28 author: Dave Welsch (@dwelsch-esi) --- + + # Separate technical documentation from the project page ## Overview The Knative project [landing page] redirects to the doc page: -`https://knative.dev/docs/`. The project landing page contains all the -elements you'd expect on an open-source software page, including case studies, -user endorsements, and links to the community. +`https://knative.dev/docs/`. The project landing page contains all the elements +you'd expect on an open-source software page, including case studies, user +endorsements, and links to the community. It also includes the technical documentation in the banner menu. This arrangement conflates the project and the technical documentation, mixing -marketing and technical information. +marketing and technical information. It's helpful to users if there's a clear separation between technical documentation and other information. The technical documentation is goal-driven @@ -29,14 +31,12 @@ Audience: All Type: All - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -44,7 +44,6 @@ Related material in the current doc: - https://github.com/knative/ - https://github.com/knative/docs/ - Suggested changes: The simplest solution to untangling the documentation from the landing page is @@ -60,7 +59,6 @@ probably to: - Remove the version drop-down from the project landing page (and the other non-documentation project pages). - # Rename pages ## Overview @@ -91,7 +89,6 @@ Related material in the current doc: - https://knative.dev/docs/serving/ - https://knative.dev/docs/eventing/ - Suggested changes: - Remove "About" from titles: @@ -99,16 +96,15 @@ Suggested changes: - "About Eventing Features" > "Eventing Features" - and so on. - Rename "Tutorial" to "Tutorials" (there is more than one tutorial here). -- Make verb tense consistent in procedure titles. Use "-ing" verbs to title tasks - and processes (thiis is already done in the majority of cases!): +- Make verb tense consistent in procedure titles. Use "-ing" verbs to title + tasks and processes (this is already done in the majority of cases!): - [Configure Broker defaults] > "Configuring Broker defaults" - [Install Knative using quickstart] > "Installing Knative using quickstart" - and so on. -- In [Serving] and [Eventing], rename "Developer Topics" and - "Admin Topics" to "Developer Tasks" and "Admin Tasks" to cue readers. -- Retitle this page: - [Knative Eventing - The Event-driven application platform for Kubernetes] - to "Eventing". +- In [Serving] and [Eventing], rename "Developer Topics" and "Admin Topics" to + "Developer Tasks" and "Admin Tasks" to cue readers. +- Retitle this page: [Knative Eventing - The Event-driven application platform + for Kubernetes] to "Eventing". - Rename "Knative CLI" to "CLI tools". - Make TOC titles agree with page titles. Some examples (not a complete list): - Change "Install the Knative CLI" in the TOC to match the page title: @@ -117,8 +113,7 @@ Suggested changes: - Change "About Apache Kafka Broker" in the TOC to match the page title: [Knative Broker for Apache Kafka]. - Rename "About" in the landing page banner to something less misleading: "Why - Knative?", "Testimonials and Case Studies", or "Endorsements". - + Knative?", "Testimonials and Case Studies", or "Endorsements". # Update technical overview @@ -130,11 +125,11 @@ section is in the current documentation, but be much more comprehensive. This conceptual overview serves two purposes: 1. It helps potential users evaluate whether Knative is the right solution to -their problem; + their problem; 2. It provides all users with enough background information to understand the -instructional and reference material later in the documentation. User don't have -to read it all before proceeding, but they will refer to it when they don't -understand how the product's pieces fit together. + instructional and reference material later in the documentation. User don't + have to read it all before proceeding, but they will refer to it when they + don't understand how the product's pieces fit together. Audience: All @@ -156,26 +151,25 @@ Related material in the current doc: - https://knative.dev/docs/serving/request-flow/ - Almost any page currently titled "About (something)" - Suggested changes: Update the "Concepts" page to be a comprehensive conceptual overview of the -entire system. Start with an introduction that explains what the product is -and what problems it is designed to solve. This information should be accessible -to someone who is not an expert container developer or admin. If some background +entire system. Start with an introduction that explains what the product is and +what problems it is designed to solve. This information should be accessible to +someone who is not an expert container developer or admin. If some background knowledge is required to understand the concepts, state what that knowledge is. Follow with a description of the product architecture that explains its components and how they interoperate. From the CNCF website: - Knative is a developer-focused serverless application layer which is a great - complement to the existing Kubernetes application constructs. Knative consists - of three components: an HTTP-triggered autoscaling container runtime called - “Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called - “Knative Eventing”, and a developer-focused function framework which leverages - the Serving and Eventing components, called "Knative Functions". +Knative is a developer-focused serverless application layer which is a great +complement to the existing Kubernetes application constructs. Knative consists +of three components: an HTTP-triggered autoscaling container runtime called +“Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called +“Knative Eventing”, and a developer-focused function framework which leverages +the Serving and Eventing components, called "Knative Functions". -Finally, explain essential but tangential topics like authenication and +Finally, explain essential but tangential topics like authentication and authorization, still at a conceptual level. # Update Installation to better orient users @@ -192,21 +186,18 @@ Audience: Admins and developers Type: Instructional - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://github.com/knative/install - Suggested changes: On the [Installing Knative] page, provide a roadmap at the top to direct users @@ -228,14 +219,12 @@ Audience: All Type: All - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -247,24 +236,23 @@ Related material in the current doc: Suggested changes: - In the [Eventing] section, move "Event Mesh" under "Concepts". -- Move the [Release Notes] to the top level of the TOC - (and change the URL to https://knative.dev/docs/relnotes/). +- Move the [Release Notes] to the top level of the TOC (and change the URL to + https://knative.dev/docs/relnotes/). - Make the "Explore Knative" button the landing page link to the conceptual - overview. Or, change the button label to "Quick Start". Its current label - is misleading. + overview. Or, change the button label to "Quick Start". Its current label is + misleading. - Remove the Eventing FAQ. It has only one entry, and that topic is covered - elsewhere in the documentation. + elsewhere in the documentation. - Are [Revisions] the only Knative Resource? Roll this menu up: - `Serving > Resources > Revisions > About Revisions` - to `Serving > Revisions > About Revisions`. + `Serving > Resources > Revisions > About Revisions` to + `Serving > Revisions > About Revisions`. # Document the kn CLI on the site ## Overview -The `kn` CLI documentation is maintained in the -[/knative/kn] repo, except for the install instrutions, which are on the doc -site. +The `kn` CLI documentation is maintained in the [/knative/kn] repo, except for +the install instructions, which are on the doc site. Consolidate the `kn` CLI documentation so that it's maintained in one place. @@ -272,33 +260,28 @@ Audience: Admin and developer Type: Reference - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://github.com/knative/ - Suggested changes: Document the `kn` CLI on the documentation website rather than linking to the -[/knative/kn] repo documentation. - +[/knative/kn] repo documentation. # Revise the Security and threat disclosure page ## Overview -The -[Knative Security and Disclosure Information] page has some misleading and +The [Knative Security and Disclosure Information] page has some misleading and confusing elements. Rewrite the introduction to this page so that it's clear what procedures and information are available. @@ -306,14 +289,12 @@ Audience: Admin Type: Instructional - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -325,15 +306,15 @@ Suggested changes: In [Reference]: Rewrite the introduction at the top of the page, including the bullet point link -to to the threat model, to: +to to the threat model, to: -"This page describes how to validate code and report security vulnerabilites in +"This page describes how to validate code and report security vulnerabilities in Knative. For a complete description of the Knative threat model, see the -[Knative security working group repo]." -Then change headings: "Verifying code signature" and "Reporting a vulnerability." +[Knative security working group repo]." Then change headings: "Verifying code +signature" and "Reporting a vulnerability." -Rename the heading "Code Signature Verification" to -"Verifying a code signature". +Rename the heading "Code Signature Verification" to "Verifying a code +signature". Rename the heading "Report a vulnerability" to "Reporting a vulnerability". @@ -351,21 +332,18 @@ Audience: All Type: Reference - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://github.com/knative/ - Suggested changes: Add a glossary to the reference section of the documentation. Include terms that @@ -380,14 +358,13 @@ refer to other glossary entries in the definition. Order the entries alphabetically. - # Review graphics ## Overview Graphics should enhance understanding by illustrating concepts and processes. Many graphics on the Knative site detract from, rather than enhance, the -usability of documentation. +usability of documentation. Review the graphics on the site to make sure they meet these criteria: @@ -406,14 +383,12 @@ Audience: All Type: Conceptual - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -429,7 +404,6 @@ Related material in the current doc: - https://knative.dev/docs/serving/request-flow/ - https://knative.dev/docs/serving/encryption/encryption-overview/ - Suggested changes: - Briefly introduce the system diagram in the [Concepts overview]. This can be a @@ -439,7 +413,6 @@ Suggested changes: - Similarly for other conceptual graphics on the site: Refer to them from the text. - # Edit for conformance to style guide ## Overview @@ -450,43 +423,41 @@ Audience: All Type: All - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://github.com/knative/ - Suggested changes: Specific Knative style rules that will have the biggest impact: -- *Use imperatives for headings of procedures.* Technical writing best practice - has traditionally been to use gerunds ("-ing" verbs), but this is okay as well. - More imporant is to be consistent. Use the same form for all procedure headings. -- *Use simple and direct language.* To the extent possible, follow the "Voice - and language" guidelines in the style guide. For example, there are 50 instances - of the word "please" in the Knative documentation. Remove these and use simple - imperative sentences for instructions. -- *Avoid statements that will soon be out of date.* This addresses - maintainability. See the [example] in the style guide. There are many instances - of the word "currently" in the Knative documentation. + +- _Use imperatives for headings of procedures._ Technical writing best practice + has traditionally been to use gerunds ("-ing" verbs), but this is okay as + well. More important is to be consistent. Use the same form for all procedure + headings. +- _Use simple and direct language._ To the extent possible, follow the "Voice + and language" guidelines in the style guide. For example, there are 50 + instances of the word "please" in the Knative documentation. Remove these and + use simple imperative sentences for instructions. +- _Avoid statements that will soon be out of date._ This addresses + maintainability. See the [example] in the style guide. There are many + instances of the word "currently" in the Knative documentation. - Spell out words to avoid abbreviations. For example: Replace "E2E" with "end to end". -- *Use simple and direct language.* For example, from [Concepts]: "The +- _Use simple and direct language._ For example, from [Concepts]: "The documentation in this section explains commonly referenced Knative concepts and abstractions, and helps to provide you with a better understanding of how Knative works" could be: "This documentation explains what Knative is for and how it works." - # Improve troubleshooting ## Overview @@ -500,14 +471,12 @@ Audience: All Type: Instructional - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -519,21 +488,19 @@ Related material in the current doc: - https://knative.dev/docs/bookstore/page-1/send-review-comment-to-broker/#step-2-create-broker - https://knative.dev/docs/bookstore/page-2/sentiment-analysis-service-for-bookstore-reviews/#prerequisite-1-install-knative-func-cli - Suggested changes: Two possible approaches: 1. Expand each troubleshooting step to explain what the step is trying to - diagnose. (Many of the current troubleshooting steps are no more than "use this - command to diagnose ..."). Make sure that there are links to each step from the - procedure where the issue can be encountered. + diagnose. (Many of the current troubleshooting steps are no more than "use + this command to diagnose ..."). Make sure that there are links to each step + from the procedure where the issue can be encountered. 2. Consolidate all the troubleshooting procedures to a single troubleshooting - guide, organized by component. Again, provide links to the relevant points in - the guide from each procedure. - Exception: The end-to-end tutorial example has a lot of troubleshooting - information. As is the case currently, it should have its own troubleshooting - guide or guides. + guide, organized by component. Again, provide links to the relevant points in + the guide from each procedure. Exception: The end-to-end tutorial example has + a lot of troubleshooting information. As is the case currently, it should + have its own troubleshooting guide or guides. # Fill out the Eventing API @@ -554,14 +521,12 @@ This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://knative.dev/docs/eventing/reference/eventing-api/ - Suggested changes: Add a brief introduction to the Eventing API, explaining what the API is for, @@ -580,8 +545,8 @@ more information: "Retry after an exponentially increasing number of seconds (1, # Write a Getting Started page The Quickstart tutorial is useful, but it doesn't fully orient new users. A -getting started page would help, with meta information about what to expect -and where to go on the documentation site. +getting started page would help, with meta information about what to expect and +where to go on the documentation site. ## Overview @@ -589,14 +554,12 @@ Audience: New users Type: Instructional - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -608,22 +571,22 @@ Suggested changes: Add a "Getting Started" page at the top level of the documentation. This page should map a reader's user role and goals to content that helps them install, -evaluate, or learn about the product, depending on their goal. For exmaple, +evaluate, or learn about the product, depending on their goal. For example, direct new users to the Quickstart tutorial, evaluators or potential buyers to -the conceptual overview, and so on. +the conceptual overview, and so on. See, for example, getting started pages for: - [Kubernetes] -- [The Update Framework] - (a little unusual because it's a specification, not a software product) +- [The Update Framework] (a little unusual because it's a specification, not a + software product) - [Python] (a kitchen-sink approach, to be sure) # Make install downloads findable Currently the binary install download links in the Installing section redirect to the release notes, where the list of download files is far down the page. -Move and relabel the download file sectionm so that the files are easy to find. +Move and relabel the download file section so that the files are easy to find. ## Overview @@ -637,7 +600,6 @@ This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -677,7 +639,6 @@ This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -694,28 +655,35 @@ so. This change probably has to be implemented in the `mkdocs` configuration. I'd start by looking at the [mkdocs config file]. - [/knative/kn]: https://github.com/knative/client [Concepts]: https://knative.dev/docs/concepts/ [Concepts overview]: https://knative.dev/docs/concepts/ -[Configure Broker defaults]: https://knative.dev/docs/eventing/configuration/broker-configuration/ +[Configure Broker defaults]: + https://knative.dev/docs/eventing/configuration/broker-configuration/ [Eventing]: https://knative.dev/docs/eventing/ -[example]: https://github.com/knative/docs/blob/main/contribute-to-docs/style-guide/voice-and-language.md#avoid-statements-that-will-soon-be-out-of-date -[Install Knative using quickstart]: https://knative.dev/docs/install/quickstart-install/ +[example]: + https://github.com/knative/docs/blob/main/contribute-to-docs/style-guide/voice-and-language.md#avoid-statements-that-will-soon-be-out-of-date +[Install Knative using quickstart]: + https://knative.dev/docs/install/quickstart-install/ [Installing Knative]: https://github.com/knative/install [Installing the Knative CLI]: https://knative.dev/docs/client/install-kn/ -[Knative Broker for Apache Kafka]: https://knative.dev/docs/eventing/brokers/broker-types/kafka-broker/ -[Knative Eventing - The Event-driven application platform for Kubernetes]: https://knative.dev/docs/eventing/ -[Knative Security and Disclosure Information]: https://knative.dev/docs/reference/security/ -[Knative security working group repo]: https://github.com/knative/community/blob/main/working-groups/security/threat-model.md -[Knative style guide]: https://github.com/knative/docs/tree/main/contribute-to-docs/style-guide +[Knative Broker for Apache Kafka]: + https://knative.dev/docs/eventing/brokers/broker-types/kafka-broker/ +[Knative Eventing - The Event-driven application platform for Kubernetes]: + https://knative.dev/docs/eventing/ +[Knative Security and Disclosure Information]: + https://knative.dev/docs/reference/security/ +[Knative security working group repo]: + https://github.com/knative/community/blob/main/working-groups/security/threat-model.md +[Knative style guide]: + https://github.com/knative/docs/tree/main/contribute-to-docs/style-guide [Kubernetes]: https://kubernetes.io/docs/setup/ [landing page]: https://knative.dev/ [Metrics]: https://knative.dev/docs/serving/autoscaling/autoscaling-metrics/ [mkdocs config file]: https://github.com/knative/docs/blob/main/mkdocs.yml [Python]: https://wiki.python.org/moin/BeginnersGuide [Reference]: https://knative.dev/docs/reference/ -[Release Notes]: https://knative.dev/docs/reference/relnotes/ +[Release Notes]: https://knative.dev/docs/reference/relnotes/ [Revisions]: https://knative.dev/docs/serving/revisions/ [Serving]: https://knative.dev/docs/serving/ [The Update Framework]: https://theupdateframework.io/docs/getting-started/ diff --git a/docs/analytics/ua-to-ga4.md b/docs/analytics/ua-to-ga4.md index 3855f90..3cb8336 100644 --- a/docs/analytics/ua-to-ga4.md +++ b/docs/analytics/ua-to-ga4.md @@ -30,7 +30,6 @@ In preparation for the migration, follow these steps: issues opened for the pilot projects listed in #108. 2. Determine which **analytics library** your project's website is using. - - Visit your project's website. - View the page source of any website page. - Search for "`https://www.google`". Look at all instances. @@ -69,7 +68,6 @@ Follow these steps: [analytics.google.com](https://analytics.google.com). 3. **Create a GA4 site tag**: - - Select **Admin** (bottom of left-nav) - Select **GA4 Setup Assistant** - Select **Get started** under **I want to create a new Google Analytics 4 @@ -82,7 +80,6 @@ Follow these steps: 4. **Open the analytics console onto your GA4 site tag** and copy the measurement ID. Continuing from the previous step: - - Select **Go to your GA4 property** from the **GA4 Setup Assistant** view of your UA property.
This will open an analytics console onto your GA4 site tag. Perform the remaining steps from your GA4 console. @@ -92,7 +89,6 @@ Follow these steps: the appropriate row of the [status table][]. 5. Rename your UA property by adding the `- UA` suffix. From the UA console: - - Select **Admin** (bottom of left-nav) - Select **Property Settings** - Change the property name (which usually matches the project name), by @@ -104,14 +100,12 @@ Follow these steps: since the GA4 setup assistant will then have automatically [connected][] your GA4 site tag from your UA config. If you aren't sure, then you can check as follows: - - **Open** the analytics console for the **UA site tag** - Under **Admin** > **GA4 Setup Assistant**, look for your GA4 property in the **Connected Property** table. If you can't find your GA4 property, then you'll have to manually add it as follows: - - Open **Admin** > **Tracking Info** > **Tracking Code**. - Open **Connected Site Tags**. - In **Enter ID of tag to connect**: enter your GA site tag (the ID starting @@ -138,7 +132,6 @@ analytics library. this will depend, in particular, on your project's site generator and setup. Here are some guidelines on how to switch over to `gtag.js`: - - [Docusaurus][]: - v1: add a `gtag: true` site configuration parameter. - v2: enable the gtag plugin. @@ -153,7 +146,6 @@ analytics library. 2. Set the GA4 ID as the main GA ID. Again, how you do this will depend on your project's site generator and setup. Here are some guidelines: - - [Docusaurus][]: - v1: set the `gaTrackingId` site configuration parameter to your project's GA4 measurement ID. diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index 539c367..f4ba814 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -47,8 +47,8 @@ all projects following text: "The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see [Trademark Usage][]". - If your project has been converted to the Series LLC model (starting in - 2025), use the following **copyright statement**: "Copyright © - $PROJECT_NAME a Series of LF Projects, LLC." + 2025), use the following **copyright statement**: "Copyright © $PROJECT_NAME + a Series of LF Projects, LLC." ## Community and license files From cbb8d42e80228b0c3a711d85c623c2b7b0062b18 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Wed, 7 Jan 2026 18:44:04 +0000 Subject: [PATCH 025/104] chore: prettify docs Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton --- analyses/0015-knative/analysis.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/analyses/0015-knative/analysis.md b/analyses/0015-knative/analysis.md index 43d3e02..5507738 100644 --- a/analyses/0015-knative/analysis.md +++ b/analyses/0015-knative/analysis.md @@ -478,8 +478,9 @@ Other suggestions: documentation site. - In "Reference": Rewrite at the top of the page: "This page describes Knative security and disclosure information." to "This page describes how to validate - code and report security vulnerabilities in Knative. For a complete description - of the Knative threat model, see the [Knative security working group repo] + code and report security vulnerabilities in Knative. For a complete + description of the Knative threat model, see the [Knative security working + group repo] (https://github.com/knative/community/blob/main/working-groups/security/threat-model.md)." Then change headings: "Verifying code signature" and "Reporting a vulnerability." From 411a3f7dad3b667d9019a589fc0aacecaddc0024 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 7 Jan 2026 18:53:27 -0500 Subject: [PATCH 026/104] [CI] Update packages and revert mdl-disable directives Signed-off-by: Patrice Chalin Signed-off-by: Bruce Hamilton --- analyses/0015-knative/analysis.md | 7 ++----- analyses/0015-knative/issues.md | 2 +- package.json | 34 +++++++++++++++---------------- 3 files changed, 20 insertions(+), 23 deletions(-) diff --git a/analyses/0015-knative/analysis.md b/analyses/0015-knative/analysis.md index 5507738..3afc975 100644 --- a/analyses/0015-knative/analysis.md +++ b/analyses/0015-knative/analysis.md @@ -6,7 +6,7 @@ modified: 2025-07-25 author: Dave Welsch (@dwelsch-esi) --- - + ## Introduction @@ -664,7 +664,7 @@ No recommendations. ## Website and infrastructure -**TBD** +> **TBD** Knative is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. @@ -712,7 +712,6 @@ only two levels for which a tech docs analysis can be requested.) -[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules [maturity-level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [cncf-servicedesk]: https://servicedesk.cncf.io @@ -843,8 +842,6 @@ The numeric rating values used in this document are as follows 5. Exemplary [criteria]: ../criteria.md -[implementation]: ./implementation.md -[issues]: ./issues.md [project-doc-website]: https://knative.dev/docs/ [project-website]: https://knative.dev/docs/ [Rating (1-5)]: #rating-values diff --git a/analyses/0015-knative/issues.md b/analyses/0015-knative/issues.md index 9a314f1..fc040ce 100644 --- a/analyses/0015-knative/issues.md +++ b/analyses/0015-knative/issues.md @@ -6,7 +6,7 @@ modified: 2025-07-28 author: Dave Welsch (@dwelsch-esi) --- - + # Separate technical documentation from the project page diff --git a/package.json b/package.json index 685fd9d..d41d791 100644 --- a/package.json +++ b/package.json @@ -42,33 +42,33 @@ "serve": "npm run docus:serve", "test": "npm run check", "typecheck": "tsc", - "update:pkgs": "npx npm-check-updates -u" + "update:packages": "npx npm-check-updates -u" }, "author": "CNCF", "license": "CC-BY-4.0", "dependencies": { - "@docusaurus/core": "3.8.1", - "@docusaurus/preset-classic": "3.8.1", - "@mdx-js/react": "^3.1.0", + "@docusaurus/core": "3.9.2", + "@docusaurus/preset-classic": "3.9.2", + "@mdx-js/react": "^3.1.1", "clsx": "^2.1.1", "prism-react-renderer": "^2.4.1", - "react-dom": "^19.1.0", - "react": "^19.1.0" + "react-dom": "^19.2.3", + "react": "^19.2.3" }, "devDependencies": { - "@docusaurus/module-type-aliases": "3.8.1", - "@docusaurus/tsconfig": "3.8.1", - "@docusaurus/types": "3.8.1", - "cspell": "^9.1.1", - "markdown-link-check": "3.13.7", - "markdownlint-cli": "^0.45.0", - "markdownlint": "^0.38.0", - "npm-check-updates": "^18.0.1", - "prettier": "^3.5.3", - "typescript": "~5.8.3" + "@docusaurus/module-type-aliases": "3.9.2", + "@docusaurus/tsconfig": "3.9.2", + "@docusaurus/types": "3.9.2", + "cspell": "^9.4.0", + "markdown-link-check": "3.14.2", + "markdownlint-cli": "^0.47.0", + "markdownlint": "^0.40.0", + "npm-check-updates": "^19.3.1", + "prettier": "^3.7.4", + "typescript": "~5.9.3" }, "private": true, - "spelling": "cSpell:ignore ACMR docus HTMLTEST loglevel pkgs -", + "spelling": "cSpell:ignore ACMR docus HTMLTEST loglevel -", "prettier": { "proseWrap": "always", "singleQuote": true From 4b360e72ad0b0b270531152ae99de1c0ccd9a060 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 4 Dec 2025 09:40:24 -0700 Subject: [PATCH 027/104] Add Helm tech doc analysis Signed-off-by: Paige Calvert Signed-off-by: Bruce Hamilton --- analyses/0016-helm/helm-analysis.md | 554 ++++++++++++++++++++++ analyses/0016-helm/helm-implementation.md | 163 +++++++ 2 files changed, 717 insertions(+) create mode 100644 analyses/0016-helm/helm-analysis.md create mode 100644 analyses/0016-helm/helm-implementation.md diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md new file mode 100644 index 0000000..3fd5e2d --- /dev/null +++ b/analyses/0016-helm/helm-analysis.md @@ -0,0 +1,554 @@ +--- +title: Helm Documentation Analysis +tags: [Helm] +created: YYYY-MM-DD +modified: YYYY-MM-DD +author: Paige Calvert (@paigecalvert) +--- + + + +## Introduction + +This document is an analysis of the effectiveness and completeness of the +[Helm][https://helm.sh/] open source software (OSS) project's documentation +and website. It is funded by the CNCF Foundation as part of its overall effort +to incubate, grow, and graduate open source cloud native software projects. + +According to CNCF best practices guidelines, effective documentation is a +prerequisite for program graduation. The documentation analysis is the first +step of a CNCF process aimed at assisting projects with their documentation +efforts. + +### Purpose + +This document was written to analyze the current state of Helm +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second +[implementation] document, , outlines an actionable plan for improvement. A +third document is an [issues list] of issues to be added to the project +documentation repository. These issues can be taken up by contributors to +improve the documentation. + +This document: + +- Analyzes the current Helm technical documentation and website +- Compares existing documentation against the CNCF’s standards +- Recommends a program of key improvements with the largest return on investment + +### Scope of analysis + +The documentation discussed here includes the entire contents of the website, +the technical documentation, and documentation for contributors and users on the +helm-www GitHub repository. + +The Helm website and documentation are written in Markdown and are compiled using the Docusaurus static +site generator with the theme-classic theme and served from the Netlify +platform. The site's code is stored on the helm-www GitHub repo. + +#### In scope + +- Website: https://helm.sh/ +- Documentation: https://helm.sh/docs/ +- Website repo: https://github.com/helm/helm-www + +#### Out of scope + +- [helm/helm](https://github.com/helm/helm), [helm/community](https://github.com/helm/community), and other Helm subrepos + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** concerns documentation for users of the Helm + software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Helm OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability + +Each section begins with summary ratings based on a rubric with appropriate +[criteria] for the section, then proceeds to: + +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help Helm users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [implementation] document breaks the recommendations down into +concrete actions that can be implemented by project contributors. Its focus is +on drilling down to specific, achievable work that can be completed in +constrained blocks of time. Ultimately, the implementation items are decomposed +into a series of [issues] and entered as GitHub [project-doc-website]/issues. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the **[implementation] plan** and **[issues] list**. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation](./?TODO=ADD-URL) +- [Contributor documentation](./?TODO=ADD-URL) +- [Website and documentation infrastructure](./?TODO=ADD-URL) + +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria] specification. + +#### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards, +and suggests possible improvements. In most cases there is more than one way to +do things. Few recommendations here are meant to be prescriptive. Rather, the +recommended implementations represent the reviewers' experience with how to +apply documentation best practices. In other words, borrowing terminology from +the lexicon of [RFCs][rfc-spec], the changes described here should be understood +as "recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. + +## Project documentation + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Helm is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria] professional-quality documentation alongside +the project code. + +| Criterion | [Rating (1-5)] | +| -------------------------- | -------------- | +| Information architecture | 2 - needs improvement | +| New user content | 2 - needs improvement | +| Content maintainability | 4 - meets or exceeds standards | +| Content creation processes | 2 - needs improvement | +| Inclusive language | 3 - meets standards | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Project Documentation here. + +The following sections contain brief assessments of each element of the Project +Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and +> especially the technical documentation, meet these criteria. (Criteria are +> copied from criteria.md) + +#### Information architecture + +**High level conceptual/“About” content** + +The Helm docs in general lack a high level overview that provides an introduction to the product, its use cases, user personas, and so on. + +There is some level of project overview/conceptual content on these pages: +- The Using Helm page (https://helm.sh/docs/intro/using_helm) does include some conceptual information about the concepts of Helm charts, repositories, and releases +- The Introduction section (https://helm.sh/docs/intro/) includes information primarily for users of Helm charts (ie, no info for chart developers). It includes a quickstart guide that walks you through installing an example chart, a page on how to install Helm, a page with info about common Helm tasks like installing, upgrading, and working with repos, and a "cheat sheet" with quick references for common CLI commands. +- There is also some high level conceptual information in the "Topics" section of the docs. For example, Helm Architecture (https://helm.sh/docs/topics/architecture). + +**Feature complete docs** + +Overall, main Helm features are documented (like variables, template functions, hooks, and the Helm CLI). + +But, there are several new features/breaking changes that need to be updated for Helm 4. For example: +- kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well (https://github.com/helm/helm/pull/13604) +- OCI install with digest (https://github.com/helm/helm-www/pull/1629) +- Multi document values files (https://github.com/helm/helm/pull/13655) +- Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) +- Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) + + +**Step-by-step instructions** + +The Helm docs don't really include tasks in the recommended "step-by-step" format. Instead, they tend to use descriptions of how a given features works, plus examples. For example, see the https://helm.sh/docs/howto/charts_tips_and_tricks/ page, which has information about how to do several tasks with Helm using paragraphs and examples. For example: + - The page on Installing Helm (https://helm.sh/docs/intro/install) is a good example of documenting one-step procedures + - Syncing Your Chart Reposiotry (https://helm.sh/docs/howto/chart_repository_sync_example) is close to a traditional step-by-step guide. It uses headings rather than numbered steps, but seems like it could easily be converted to a numbered list of steps. It also includes helpful prerequisites and examples. + + Note: While it's important for the Helm docs to use a step-by-step format for procedures where appropriate, because Helm charts are highly configurable/customizable, in many cases, it's probably more useful for chart developers to have several examples versus traditional step-by-step instructions + +The Helm docs include some tutorials on workflows like creating different types of plugins using the different supported runtimes (eg, https://helm.sh/docs/plugins/developer/tutorial-cli-plugin). There are several other pages that use a tutorial-style format that walks users through a specific example in order to explain a given task or feature. For example: +- https://helm.sh/docs/chart_template_guide/accessing_files uses a variety of examples to explain different ways to create and access named templates +- https://helm.sh/docs/chart_template_guide/notes_files walks users through an example of adding a NOTES.txt for a chart + +Tasks for key features are generally well-documented. As mentioned above, at a high level, the Helm docs would likely benefit from including more step-by-step how-tos/tutorials, but seems that the docs do include at least a few examples for each of the key Helm features. + +For the most part, tasks demonstrate atomicity and isolation of concerns, and are given relevant headings. There are some pages like "Using Helm" that would probably be better broken down into several smaller pages that users can see from the sidebar. Also, there are some places where there is extra info under a heading that one might not expect to find there. For example, under [Writing a Hook](https://helm.sh/docs/topics/charts_hooks#writing-a-hook), there is conceptual information about how hooks work, like that you can implement multiple hooks in a single resource or that multiple resources can be inplemented as the same type of hook. These are important details about how hooks work, but they are a bit hidden half way down a section whose heading uses a verb phrase. + +**Happy path/common use cases** + +Helm has a few different happy paths depending on the user persona: +- Chart users needs to understand how to install helm, install/upgrade charts, work with chart repositories, and so on +- Chart developers need to know how to work with features like values files, template functions, chart hooks, and so on + +For chart users, the "happy path" of initializing a chart repository, installing a chart, viewing release info for the chart, then uninstalling is documented in the Quickstart workflow. The Using Helm page also touches on each of the main tasks that a chart user would need to know about + +As a chart developer, it's not very clear from looking at the docs sidebar if there's a most common use case or "happy path" documented. The closest page to this is [Charts](https://helm.sh/docs/topics/charts), which does include lots of helpful info about the chart file structure, working with chart dependencies, templates and values, and more. However, it's a lot of info in one page, and it doesn't necessarily walk developers through how all these pieces should fit together to create a release. + +**Clear escalation path to get more help** + +If the docs do not suffice, there are a couple places where an escalation path is documented for users that need more help: + - The community section of the docs (which is pulled in from the Helm community repository) includes most of the helpful info about troubleshooting. For example, https://helm.sh/community/developers/#troubleshooting provides information about working with the community and searching the existing issues in the Helm repo to troubleshoot. + - There are also some minimal FAQs here: https://helm.sh/docs/faq/. They include a few questions about installing and one question about uninstalling. It looks like this information is not really an "FAQ", but rather information about installing/uninstalling Helm that might have been documented under FAQs because it lacks a more permanent home. + +The Helm docs lack clear troubleshooting steps for different common tasks. + +**API reference** + +API reference is here: https://pkg.go.dev/helm.sh/helm/v4 + +**Content accuracy** + +In general, content is accurate. The main concern in terms of accuracy would be content that is out-of-date, particular when it comes to the latest Helm v4 docs. For example: +- There are several examples throughout the docs that use the Bitnami charts (ex: Quickstart and Using Helm pages). With the recent change from Broadcom, the images for those charts are no longer available free of charge, so these examples will need to be updated with new charts +- For the Helm v4 docs, there is a fair bit of out of date content. Some of the new features haven't been fully doc'd yet +- There's also several warnings "This page has not yet been updated for Helm 4." This content needs to be evaluated and updated + +#### New user content + +**Getting started content** + +There is Getting Started section on the site homepage. It includes Helm download commands and a link to Artiact Hub where you can find Helm charts. It links users to the docs for more infomation (specifically, it links to the installing Helm and using Helm docs pages). + +In terms of “getting started” docs that are clearly labeled as such, there is both an "Introduction" section and a page named "Quickstart". However, the content in these sections is for chart users and does not include information that would be useful to chart developers just getting started. + +After completing the quickstart or reading the introduction section, there's no clear info about what the user should do next. In general, it's hard to grock the most common use cases for Helm from looking at the docs table of contents, so it's not clear the user would be able to intuit how they could use Helm. + +This Next Steps page in the Chart Template Guide does provide a good example of pointing chart developers to more information about chart development: https://helm.sh/docs/chart_template_guide/wrapping_up + +**Step-by-step install procedures** + +The installation steps for Helm are really just single comamnds (ie, one-step procedures) for a variety of different install environments: https://helm.sh/docs/intro/install + +These install docs include code blocks that have a "copy" button which allows them to be easily copy-pasted. + +#### Content maintainability & site mechanics + +**Search** + +The documentation is searchable (it uses Algolia DocSearch). + +**Localization/i18n** + +The Helm website is localized. Helm.sh uses Docusaurus' built-in localization/translations feature to allow users to toggle between different languages. The localization process documented here: https://helm.sh/community/localization. + +**Versioning** + +The versioning process for the Helm website is documented in the readme: https://github.com/helm/helm-www/blob/main/README.md#versioning: + - Helm.sh releases a new version of the docs with each major release + - Helm.sh uses the version number in the URL path for non-latest versions of the product (the latest version is served at the main /docs/ path with no version number) + - Version labels on the site are updated to use the latest minor/patch version + +#### Content creation processes + +**Contribution process for documentation** + +Documentation contribution how-tos are documented in the helm-www README and in the Community section (eg https://helm.sh/community/localization) + +However, there isn't a clearly documented ongoing process for how often PRs/issues get reviewed, requirements for docs PRs in order to be approved, a style guide, issue triage plan, etc. + +**Code release process** + +The code release process does account for documentation creation and updates in that PR include a checkbox for "this PR includes documentation", if applicable. + +However, there doesn't seem to be a requirement that a documentation PR exists for a code change (if needed) before a code change is approved is merged. + +**Docs PR review/approval** + +Maintainers of the helm-www repo and core project maintainers can review and approve docs PRs. + +**Website owners** + +Maintainers are clearly listed in the OWNERS file https://github.com/helm/helm-www/blob/main/OWNERS. Maintiners were recently updated to add/remove as needed, but there is not an ongoing process for reviewing and updating the list of maintainers. + +#### Inclusive language + +There do not appear to be any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website. + +The docs do occassionally use language like "simple", "easy", etc. Example: https://helm.sh/docs/topics/registries/#migrating-from-chart-repos + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Information architecture + +The information architecture could benefit from the following: +- The Introduction, How-to, Topics, Best Practices, Chart Template Guide, and FAQs sections should all be reviewed to see where there is redundant content that can be condensed. With the current naming of these sections, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. +- Could consider creating high-level categories based on the major feature area. For example, a section on working with chart registries, plugins, variables/templates, and so on. +- The Chart Template Guide is a better example of having + +#### New user content + +The site could use a more cleraly labeled "getting started" section, with guides for all main user personas (both chart users and chart developers). For example, a quick start that shows how to create and release a simple chart and/or a page that explains that chart dev "happy path", including all the main tasks a chart developer should consider as part of creating and publishing a chart for their app. Could probably use lots of the content in Using Helm to create getting started info for chart developers + +#### Content maintainability & site mechanics + +Search, locaization, and versioning functionality all looks good/is useable on the site. + +Helm.sh is in need of a better process for reviewing and accepting localized documentation changes (including adding a new locale). There are several open PRs from people adding translations to the site, but not a good process for determining how those get reviewed, how drift is tracked/updated, and so on. A good example of this is here: https://opentelemetry.io/docs/contributing/localization/. + +#### Content creation processes + +The contributors docs could be better centralized and easier to search, maybe in a "Contribute to the Docs" section. Currently, the contributor info is spread across the readme, the ARCHITECTURE_DECISIONS doc, as well as the community section, which makes it hard to find, and hard to tell when it's out of date. + +Also, the team could make docs more "part of the definition of done" for new features. For example, when a docs update is needed, creating the docs PR could be required before a new feature PR to be merged. This would help ensure that the docs stay up to date. + +#### Inclusive language + +Review the docs for terms like "simply" and "easy" and remove them. + +Helm.sh could also choose an existing, industry-accepted style guide to point contributors to, including a link to the inclusive language website. This would help maintain inclusive, clear word choice throughout. + +## Contributor documentation + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Helm is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria] professional-quality documentation alongside +the project code. + +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | 3 - meets standards | +| Beginner friendly issue backlog | 2 - needs improvement | +| “New contributor” getting started content | 3 - meets standards | +| Project governance documentation | 3 - meets standards | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Contributor Documentation +> here. + +The following sections contain brief assessments of each element of the +Contributor Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the contributor documentation might +> be contained in the documentation repository. (Criteria are copied from +> criteria.md) + +#### Communication methods documented + +**Slack and dev meetings** + +The Helm Slack channels are prominently linked in the Join the Community section on the landing page. This section also has info about upcoming events, weekly developer standups (with info on how to join), and more. Additionally, the Community section of the website (https://helm.sh/community) also includes this information. + +**GitHub links** + +Users can find direct links to the Helm GitHub organization/repositories in a couple ways: +- There are links on the site homepage, in the community section, and in the footer to the main Helm github +- There's an edit this page link on every docs page that allows the user to open it in the helm-www repo in github + +**Mailing lists** + +Mailing lists are documented here: https://helm.sh/community/communication/#mailing-lists + +#### Beginner friendly issue backlog + +Docs issues are not very well triaged. There are nearly 100 open docs issues, many irrelevant to the new site. There is also no clear traige plan or timelines in place for addressing issues or reviewing them for freshness. + +There is a “good first issue” label, which new contributors can use to make code or documentation contributions. + +In general, issues are well-documented and include helpful descriptions beyond just a title. There doesn't seem to be an issue template. + +#### New contributor getting started content + +**Community docs** + +The website has a community section here: https://helm.sh/community. This is automatically pulled in from the helm/community repo using a plugin. + +**Docs for first-time contributors** + +Helm.sh has the following content that does a good job of providing info for first-time contributors: +- https://helm.sh/community/developers +- https://helm.sh/community/#your-first-contribution + +Also, while there's nothing specifically labeled "get help" on the site, there's plenty of places where the slack channels, dev meetings, etc are listed for users + +#### Project governance documentation + +Is Project governance clearly is documented here: https://helm.sh/community/governance/ + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Beginner friendly issue backlog + +Improved standards/practices around regular issue triage and maintaining issue freshness could help make the issue backlog a little easier to navigate. + +#### New contributor getting started content + +While new contributor docs are well documented, it also couldn't hurt to add a heading (in the Community docs, perhaps) that includes the terms "troubleshooting" or "get help", in case people search to website for those terms. + +## Website and infrastructure + +Helm is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | 3 - meets standards | +| Meets min website req. (for maturity level) | 3 - meets standards | +| Usability, accessibility, and design | 4 - meets or exceeds standards | +| Branding and design | 4 - meets or exceeds standards | +| Case studies/social proof | 1 - not present | +| SEO, Analytics, and site-local search | 3 - meets standards | +| Maintenance planning | 3 - meets standards | +| A11y plan & implementation | 3 - meets standards | +| Mobile-first plan & impl. | 3 - meets standards | +| HTTPS access & HTTP redirect | 3 - meets standards | +| Google Analytics 4 for production only | 1 - not present | +| Indexing allowed for production server only | 3 - meets standards | +| Intra-site / local search | 3 - meets standards | +| Account custodians are documented | 2 - needs improvement | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Website and documentation +> infrastructure here. + +The following sections contain brief assessments of each element of the Website +and documentation infrastructure rubric. + +> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the website infrastructure criteria +> depend on the tools (static site generator, website framework and hosting, +> analytics tools, etc.) and processes (project CI, release procedures, +> governance, etc.) used to produce the documentation. (Criteria are copied from +> criteria.md) + +#### Single-source requirement + +Nearly all website pages reside in a single repo (helm/helm-www). The exception to this is the Community section of the website, which pulls in docs from the helm/community repo using a plugin. This is documented in the readme: https://github.com/helm/helm-www?tab=readme-ov-file#community-documentation. Additionally, the "Edit this page" link at the bottom of the community pages properly sends users to the page source in the helm/community repo to prevent users from accidentally editing the wrong source. + +The way the community section is set up, there is no need for maintainers to keep multiple versions of the community docs up-to-date/in sync. And, Helm maintainers have indicated that pulling in the community doc in this way is useful for making the information more findable for users. + +#### Minimal website requirements + +Listed here are the minimal website requirements for projects based on their +[maturity level][maturity-level], either incubating or graduated. (These are the +only two levels for which a tech docs analysis can be requested.) + + + +| Criterion | Incubating Requirement | Graduated Requirement | +| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | +| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + + + +[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[maturity-level]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[cncf-servicedesk]: https://servicedesk.cncf.io + +#### Usability, accessibility and devices + +**Usability / mobile experience** + +The website usable from mobile (doc pages are readable, and all website features are accessible from mobile including the top-nav, site search and in-page table of contents) + +**Accessibility** + +A Chrome Lighthouse audit on the helm.sh site gives a score of 94/100 for accessibility. It reports that the light blue link color (such as for the word Kubernetes on the landing page subtitle) is not high enough contrast for color-impaired readers. It also reports that there are some links that use only color to differentiate them from the surrounding text. + +Did not test the text-to-speech, but the amount of code and special characters in the text generally means that text-to-speech is not likely to be a good experience for users. + +#### Branding and design + +There is an easily recognizable brand for the project (logo + color scheme) that is used across the website consistently. The website's typography is consistent and easy to read. The only exception is that the font used for headings can be somewhat difficult to read for some of the letters. + +#### Case studies/social proof + +There is a logo wall of participating organizations featured at the bottom of the landing page (called "Supporters"). There is not a list of Helm users, but perhaps the supporters are also the users that would be listed + +There do not appear to be any case studies or testimonials available for the project that are documented on the website. I do see Helm case studies on the CNCF website, but not sure how recent or relevant these are: https://www.cncf.io/case-studies/?_sft_lf-project=helm + +#### SEO, Analytics and site-local search + +**Analytics** + +Analytics is not set up for the site. + +**SEO, Indexing, and Search** + +Local intra-site search is available from the website. Search is powered by Algolia DocSearch. The production site is well-indexed thanks to a built-in Algolia config for Docusaurus site, and is reindexed daily (this schedule is controlled by an algolia crawler setting). + +**Account custodians** + +The current custodian(s) of the following Algolia account is not specifically documented, but the repo does have an OWNERS file. + +#### Maintenance planning + +**Website tooling** + +The website uses Docusaurus, which has a robust open source community and is actively maintained. Before Helm.sh was migrated to Docusaurus, the migration and tooling was discussed with the CNCF tech docs team to make sure it was recommended. + +**Website maintainers** + +There is no indication that the project is actively cultivating website maintainers from the community. + +**Build times** + +Build times can be quite long (10+ mins). This is because Docusaurus builds a separate site for each locale, and Helm.sh has several locales. There is a script in the repo that is designed to use the Docusaurus cache to reduce build times (particularly useful for more quickly generating previews on PRs). This script tends to have varied results, but can reduce build times down to a reasonable 1-3 mins. + +#### Other + +The website is accessible via HTTPS and requests using HTTP are properly redirected to the HTTPS URLs. + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Case studies/social proof + +Could add a link to case studies on the landing page and/or prioritize writing and publishing case studies in the blog + +#### SEO, Analytics and site-local search + +Add analytics to the production server (could use Google Analytics (GA) 4), and ensure that 404 reports are collected and tracked using the analytics service. + +#### Maintenance planning + +Consider troubleshooting the existing script to see why it inconsistently reduces build times. + +#### References and notes + +##### Rating values + +The numeric rating values used in this document are as follows + +1. Not present +2. Needs improvement +3. Meets standards +4. Meets or exceeds standards +5. Exemplary + +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues-list.md +[project-doc-website]: ./?https://helm.sh/docs/ +[project-website]: ./?https://helm.sh/ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md \ No newline at end of file diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/0016-helm/helm-implementation.md new file mode 100644 index 0000000..f8d4dab --- /dev/null +++ b/analyses/0016-helm/helm-implementation.md @@ -0,0 +1,163 @@ +--- +title: Implementing Helm Doc Improvements +tags: [Helm] +--- + + + +## Introduction + +This document provides actionable suggestions for improving the Helm +technical documentation. + +For an analysis and general discussion of recommendations on Helm technical +documentation, see [analysis.md](helm-analysis.md). + +### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards and +suggests possible improvements. In most cases there is more than one way to do +things. Few recommendations here are meant to be prescriptive. Rather, +recommendations are based on documentation best practices as understood by the +reviewers. The recommended implementations represent the reviewers' experience +with how to apply those best practices. In other words, borrowing terminology +from the lexicon of [RFCs][rfc-keywords], the changes described here should be +understood as "recommended" or "should" at the strongest, and "optional" or +"may" in many cases. Any "must" or "required" actions are clearly denoted as +such, and pertain to legal requirements such as copyright and licensing issues. + +The top-level documentation recommendations for this project are: + +> AUTHOR NOTE: Provide a summary or outline of the recommendations. Depending on +> the analysis findings, recommended actions might be organized into two or +> three high-level items that contain multiple actions, or might just be a list +> of independent changes. For examples, see a completed implementation plan such +> as 0008-Backstage or 0010-etcd. + +## Reorganize the main docs sidebar + +As is, it is difficult for users to find information in the main docs sidebar. Some of the categories seek to group information by content type (How-To and Topics), while other categories group content by the specific product area (Chart Template Guide and Plugins). This inconsistency makes it difficult to intuit where the info you want might be located. It also makes it harder for docs contributors to decide where to situate a new page. + +The overall organization could be much improved by following a more consistent pattern: +- Include clearly labeled intro/new user content at the top +- At the highest level, group content by product area (for example, some product areas might be plugins, charts, and chart repositories) +- Within each product area, add concepts and tasks for the different user personas/use cases. For example, for charts, there need to be docs for users installing and using charts, as well as for users developing and releasing charts +- Consider pulling out reference material like CLI docs or info about policies to the top level, unassociated with a specific product area + +Here is a proposed sidebar based on the above (note that this proposal attempts to keep existing pages intact as much as possible to make this easier to implement): + +- [Docs Home](https://helm.sh/docs/) +- Helm 4 + - What's New? (https://helm.sh/docs/overview) + - [Full Changelog](https://helm.sh/docs/changelog) +- Introduction + - Overview (A new Helm Overview page. Use the existing content in [Helm Architecture](https://helm.sh/docs/topics/architecture) and add content from [Three Big Concepts](https://helm.sh/docs/intro/using_helm#three-big-concepts) in _Using Helm_) + - [Quickstart](https://helm.sh/docs/intro/quickstart) + - [Installing Helm](https://helm.sh/docs/intro/install) + - [Kubernetes Distribution Guide](https://helm.sh/docs/topics/kubernetes_distros) + - [Glossary](https://helm.sh/docs/glossary/) +- Install and Use Charts + - [Using Helm](https://helm.sh/docs/intro/using_helm) + - [Cheat Sheet](https://helm.sh/docs/intro/CheatSheet) + - Post Rendering (from https://helm.sh/docs/topics/advanced#post-rendering. Recommend breaking up "Advanced Helm Techniques" into two pages: Post-Rendering and Configure Store Backends. The title "Advanced Helm Techniques" makes it hard for users to guess what might be in it) + - Configure Storage Backends (from https://helm.sh/docs/topics/advanced#storage-backends) + - [Permissions management for SQL storage backend](https://helm.sh/docs/topics/permissions_sql_storage_backend) + - [Helm Provenance and Integrity](https://helm.sh/docs/topics/provenance) + - [Role-based Access Control](https://helm.sh/docs/topics/rbac) +- Develop Charts + - [Charts](https://helm.sh/docs/topics/charts) (eventually, this page could probably be broken out into smaller pages) + - [Chart Hooks](https://helm.sh/docs/topics/charts_hooks) + - [Chart Tests](https://helm.sh/docs/topics/chart_tests) + - [Library Charts](https://helm.sh/docs/topics/library_charts) + - Chart Values and Templates + - [most of the existing pages under [Chart Template Guide](https://helm.sh/docs/chart_template_guide/)] + - [The .helmignore file](https://helm.sh/docs/chart_template_guide/helm_ignore_file) + - [Creating a NOTES.txt File](https://helm.sh/docs/chart_template_guide/notes_files) + - Chart Development Best Practices + - [Chart Development Tips and Tricks](https://helm.sh/docs/howto/charts_tips_and_tricks) + - [other existing bets practices pages] +- Release Charts + - [The Chart Repository Guide](https://helm.sh/docs/topics/chart_repository) + - [Use OCI-based registries](https://helm.sh/docs/topics/registries) + - [Syncing Your Chart Repository](https://helm.sh/docs/howto/chart_repository_sync_example) + - [Chart Releaser Action to Automate GitHub Page Charts](https://helm.sh/docs/howto/chart_releaser_action) +- Use and Develop Plugins + - [Overview](https://helm.sh/docs/plugins/overview) + - [Using Plugins](https://helm.sh/docs/plugins/user/) + - [Developing Plugins](https://helm.sh/docs/plugins/developer/) + - [existing tutorials] +- [Helm Commands](https://helm.sh/docs/helm/) +- [Go SDK](https://helm.sh/docs/sdk/) +- Policies + - [Release Schedule Policy](https://helm.sh/docs/topics/release_policy) + - [Helm Version Support Policy](https://helm.sh/docs/topics/version_skew) + +## Add a technical/conceptual overview of Helm + +Put architecture, operating principles, and other conceptual explanations in a high-level technical overview. + +There is some existing content in the site that can probably be used to build this overview, particularly in [Helm Architecture](https://helm.sh/docs/topics/architecture). The goal of this new overview would be to give new users a good foundation to get started with Helm, including an understanding of the most common use cases, the typical user personas, and the primary concepts/terms to know. + +## Prune out-of-date content + +There are several pages in the docs that are likely out-of-date or otherwise no longer relevant. For example: +- "FAQs" https://helm.sh/docs/faq/installing and https://helm.sh/docs/faq/uninstalling +- Best practices section: https://helm.sh/docs/chart_best_practices/ +- Tips and tricks: https://helm.sh/docs/howto/charts_tips_and_tricks + +For each of these pages/section, if possible, prefer distributing the content across other existing pages so that these pages might be deleted. For example, could the RBAC best practices listed at https://helm.sh/docs/chart_best_practices/rbac be instead incorporated into the existing page on [Role-Based Access Control](https://helm.sh/docs/topics/rbac)? + +Alternatively, if the content is still important and doesn't fit well elsewhere in the docs, make the necessary updates so that it is up-to-date and accurate. + +## Finish the Helm v4 docs + +### Document all the new features released with Helm 4 + +Make sure that all the Helm 4 features, improvements, and fixes are documented. For example: +- kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well (https://github.com/helm/helm/pull/13604) +- OCI install with digest (https://github.com/helm/helm-www/pull/1629) +- Multi document values files (https://github.com/helm/helm/pull/13655) +- Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) +- Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) + +### Review and update all the pages with the "This page has not yet been updated for Helm 4" warning + +This warning was added to several pages in the Helm 4 docs to indicate that they've not yet been updated: + +"This page has not yet been updated for Helm 4. Some of the content might be inaccurate or not applicable to Helm 4. For more information about the Helm 4 new features, improvements, and breaking changes, see Helm 4 Overview." + +Review all the pages where this warning appears, and review them to make any necessary updates. Then, remove the warning. + +## Rewrite tasks as step-by-step procedures + +CNCF strongly recommends that tasks and procedures are written as step-by-step instructions. For example: + +```mdx +To do [task]: +1. Do the first step. +1. Do the second step. +``` + +This is also an industry-standard for technical documentation (See the Google Developer Docs style guide https://developers.google.com/style/procedures) + +The Helm docs tend not to use step-by-step instructions for tasks and procedures. This is not ideal because it can cause conpetual/procedural/reference content to be inadvertently blended together, which makes information less findable to users. For users looking to accomplish a task, it can be challenging to weed through paragraphs. + +To improve the docs user experience, all tasks that are documented in the Helm docs should be reformatted or rewritten so that they use numbered steps. For example, each of the headings in https://helm.sh/docs/howto/chart_repository_sync_example could be converted to a numbered step in an ordered list. Assigning numbers to each item would make it immediately clearer that this is a prcedure that can be followed in order. + +## Improve docs contribution processes + +### Create and publish a clear process for adding and maintaining localized documentation + +There is not currently a process for adding a new locale to the docs, maintaining/tracking drift in existing locales, or reviewing PRs to localized content. + +This has led to several locales which are minimally translated and are lacking a plan or committment from community members for ongoing maintenance. It has also led to several localization PRs and issues sitting open and unreviewed indefinitely, without contributors understanding what they need to do to get them merged. + +The CNCF docs team has share the following guidance that the OpenTelemetry project uses for localizing their docs: https://opentelemetry.io/docs/contributing/localization/ + +The Helm docs maintainers should review these guidelines and make a plan for rolling out similar processes. + +### Create and publish a clear process for triaging the issue backlog and reviewing PRs + +Similar to above, the helm-www repo should have clearer processes for triaging issues and reviewing/merging PRs. As is, there are dozens of open issues and PRs that are not regularly reviewed for freshness or otherwise responded to by maintainers. Agreeing on and publishing a set of processes could make it easier for maintainers and contributors to understand how to review issues/PRs, and how long it should take for issues/PRs to be reviewed. + +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 \ No newline at end of file From 984f978c3e539b28c4496ca6f841755b2819bec1 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 4 Dec 2025 10:24:01 -0700 Subject: [PATCH 028/104] Edit links and add issues list doc Signed-off-by: Paige Calvert Signed-off-by: Bruce Hamilton --- analyses/0016-helm/helm-analysis.md | 85 ++++++-------------------- analyses/0016-helm/helm-issues-list.md | 52 ++++++++++++++++ 2 files changed, 70 insertions(+), 67 deletions(-) create mode 100644 analyses/0016-helm/helm-issues-list.md diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md index 3fd5e2d..90ec096 100644 --- a/analyses/0016-helm/helm-analysis.md +++ b/analyses/0016-helm/helm-analysis.md @@ -1,7 +1,7 @@ --- title: Helm Documentation Analysis tags: [Helm] -created: YYYY-MM-DD +created: 2025-12-04 modified: YYYY-MM-DD author: Paige Calvert (@paigecalvert) --- @@ -11,7 +11,7 @@ author: Paige Calvert (@paigecalvert) ## Introduction This document is an analysis of the effectiveness and completeness of the -[Helm][https://helm.sh/] open source software (OSS) project's documentation +[Helm][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. @@ -25,7 +25,7 @@ efforts. This document was written to analyze the current state of Helm documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second -[implementation] document, , outlines an actionable plan for improvement. A +[implementation] document outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. @@ -80,20 +80,20 @@ The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed -into a series of [issues] and entered as GitHub [project-doc-website]/issues. +into a series of [issues] and entered as GitHub [issues](https://github.com/helm/helm-www/issues). ### How to use this document Readers interested only in actionable improvements should skip this document and -read the **[implementation] plan** and **[issues] list**. +read the **[implementation] plan** and **[issues list]**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: -- [Project documentation](./?TODO=ADD-URL) -- [Contributor documentation](./?TODO=ADD-URL) -- [Website and documentation infrastructure](./?TODO=ADD-URL) +- [Project documentation](#project-documentation) +- [Contributor documentation](#contributor-documentation) +- [Website and documentation infrastructure](#website-and-infrastructure) Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. @@ -112,17 +112,9 @@ to legal requirements such as copyright and licensing issues. ## Project documentation -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - Helm is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -> AUTHOR NOTE: or - -Helm is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside -the project code. - | Criterion | [Rating (1-5)] | | -------------------------- | -------------- | | Information architecture | 2 - needs improvement | @@ -133,15 +125,9 @@ the project code. ### Comments -> AUTHOR NOTE: make any overall comments about the Project Documentation here. - The following sections contain brief assessments of each element of the Project Documentation rubric. -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and -> especially the technical documentation, meet these criteria. (Criteria are -> copied from criteria.md) - #### Information architecture **High level conceptual/“About” content** @@ -275,15 +261,13 @@ The docs do occassionally use language like "simple", "easy", etc. Example: http ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - #### Information architecture -The information architecture could benefit from the following: -- The Introduction, How-to, Topics, Best Practices, Chart Template Guide, and FAQs sections should all be reviewed to see where there is redundant content that can be condensed. With the current naming of these sections, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. -- Could consider creating high-level categories based on the major feature area. For example, a section on working with chart registries, plugins, variables/templates, and so on. -- The Chart Template Guide is a better example of having +It will be helpful to find greater specificity in the naming strategy for categories. With the current naming of the sections in the sidebar, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. Many sections are named by content type (how-to, topics, faqs, best practices). This is fine, but can be challenging to maintain and find content when it's not clear what qualifies as each content type (for example, Topics has become a large catch-all category). By using more specific categories that align with a given product area or use case, it'll be more obvious where info can be found. + +Additionally, content throughout should be reviewed to see where there is redundant content that can be condensed. For example, lots of the pages in Topics, FAQs, Introduction, Best Practices feels out-of-date or redundant with other pages + +Finally, procedures should be converted to step-by-step instructions for better readability. #### New user content @@ -297,7 +281,7 @@ Helm.sh is in need of a better process for reviewing and accepting localized doc #### Content creation processes -The contributors docs could be better centralized and easier to search, maybe in a "Contribute to the Docs" section. Currently, the contributor info is spread across the readme, the ARCHITECTURE_DECISIONS doc, as well as the community section, which makes it hard to find, and hard to tell when it's out of date. +The contributors docs could be better centralized and easier to search, maybe in a "Contribute to the Docs" section. Currently, the contributor info is spread across the README, [CONTRIBUTING](https://github.com/paigecalvert/helm-www/blob/main/CONTRIBUTING.md), and the Community section, which makes it a bit harder to find, and harder to tell when it's out of date. Also, the team could make docs more "part of the definition of done" for new features. For example, when a docs update is needed, creating the docs PR could be required before a new feature PR to be merged. This would help ensure that the docs stay up to date. @@ -309,17 +293,9 @@ Helm.sh could also choose an existing, industry-accepted style guide to point co ## Contributor documentation -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - Helm is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -> AUTHOR NOTE: or - -Helm is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside -the project code. - | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | | Communication methods documented | 3 - meets standards | @@ -329,17 +305,9 @@ the project code. ### Comments -> AUTHOR NOTE: make any overall comments about the Contributor Documentation -> here. - The following sections contain brief assessments of each element of the Contributor Documentation rubric. -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the contributor documentation might -> be contained in the documentation repository. (Criteria are copied from -> criteria.md) - #### Communication methods documented **Slack and dev meetings** @@ -384,9 +352,6 @@ Is Project governance clearly is documented here: https://helm.sh/community/gove ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - #### Beginner friendly issue backlog Improved standards/practices around regular issue triage and maintaining issue freshness could help make the issue backlog a little easier to navigate. @@ -419,19 +384,9 @@ have [_very high_][criteria] standards for documentation. ### Comments -> AUTHOR NOTE: make any overall comments about the Website and documentation -> infrastructure here. - The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. -> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the website infrastructure criteria -> depend on the tools (static site generator, website framework and hosting, -> analytics tools, etc.) and processes (project CI, release procedures, -> governance, etc.) used to produce the documentation. (Criteria are copied from -> criteria.md) - #### Single-source requirement Nearly all website pages reside in a single repo (helm/helm-www). The exception to this is the Community section of the website, which pulls in docs from the helm/community repo using a plugin. This is documented in the readme: https://github.com/helm/helm-www?tab=readme-ov-file#community-documentation. Additionally, the "Edit this page" link at the bottom of the community pages properly sends users to the page source in the helm/community repo to prevent users from accidentally editing the wrong source. @@ -456,7 +411,6 @@ only two levels for which a tech docs analysis can be requested.) -[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules [maturity-level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [cncf-servicedesk]: https://servicedesk.cncf.io @@ -517,9 +471,6 @@ The website is accessible via HTTPS and requests using HTTP are properly redirec ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - #### Case studies/social proof Could add a link to case studies on the landing page and/or prioritize writing and publishing case studies in the blog @@ -545,10 +496,10 @@ The numeric rating values used in this document are as follows 5. Exemplary [criteria]: ../criteria.md -[implementation]: ./implementation.md -[issues list]: ./issues-list.md -[project-doc-website]: ./?https://helm.sh/docs/ -[project-website]: ./?https://helm.sh/ +[implementation]: ./helm-implementation.md +[issues list]: ./helm-issues-list.md +[project-doc-website]: https://helm.sh/docs/ +[project-website]: https://helm.sh/ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md \ No newline at end of file diff --git a/analyses/0016-helm/helm-issues-list.md b/analyses/0016-helm/helm-issues-list.md new file mode 100644 index 0000000..89c251c --- /dev/null +++ b/analyses/0016-helm/helm-issues-list.md @@ -0,0 +1,52 @@ +--- +title: _PROJECT_ Umbrella Issue and Issues List +tags: [_PROJECT_] +--- + +## Overview + +> AUTHOR NOTES: +> +> - Provide an outline or high-level description of the recommended changes. +> Note any general patterns that occur throughout the documentation, such as a +> lack of step-by-step procedures. +> +> -Items might be disjoint and unrelated; that's OK. If there are high-level +> items that must be broken down into smaller issues, use the high-level items +> to organize the issues in this plan. Otherwise, list issues in order from the +> analysis document. This is an improvement plan, not a legal brief. +> +> - The following is boilerplate language to include in the umbrella issue in +> the repo: + +This issue tracks recommended changes resulting from an analysis of the +_PROJECT_ documentation commissioned by CNCF. The analysis and supporting +documents are here: https://github.com/cncf/techdocs/tree/main/analyses under +`00NN-project`. + +The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo: +https://github.com/cncf/techdocs/issues + +## Umbrella issue + +> AUTHOR NOTE: Link to the umbrella issue in the project's documentation repo + +## Issues + +This is a list of issues representing the recommended work on the _PROJECT_ +website and technical documentation. + +> AUTHOR NOTE: Consider using the [issue](issue.md) template. + +### Issue: Item 1 + +> AUTHOR NOTE: Summarize the documentation changes prescribed by this issue. Use +> enough detail to estimate the scope of the issue. Fine-grained detail can go +> in the issue itself. In the GitHub umbrella issue, link to the sub-issue using +> a Markdown checkbox as shown below. + +- [ ] `https://github.com/_PROJECT_/repo/issues/NNN` + +### Issue: Item 2 + +> AUTHOR NOTE: ... and so on. From 4251e25db2dc43928dec88d48fb8c345da51c633 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 8 Dec 2025 14:49:44 -0700 Subject: [PATCH 029/104] update proposed sidebar & typo and md formatting fixes Signed-off-by: Paige Calvert Signed-off-by: Bruce Hamilton --- analyses/0016-helm/helm-analysis.md | 579 +++++++++++++++------- analyses/0016-helm/helm-implementation.md | 217 +++++--- 2 files changed, 555 insertions(+), 241 deletions(-) diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md index 90ec096..25e8947 100644 --- a/analyses/0016-helm/helm-analysis.md +++ b/analyses/0016-helm/helm-analysis.md @@ -4,6 +4,7 @@ tags: [Helm] created: 2025-12-04 modified: YYYY-MM-DD author: Paige Calvert (@paigecalvert) +cSpell:ignore: paigecalvert subrepos kstatus Bitnami --- @@ -23,8 +24,8 @@ efforts. ### Purpose This document was written to analyze the current state of Helm -documentation. It aims to provide project leaders with an informed understanding -of potential problems in current project documentation. A second +documentation. It aims to provide project leaders with an informed +understanding of potential problems in current project documentation. A second [implementation] document outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to @@ -33,18 +34,20 @@ improve the documentation. This document: - Analyzes the current Helm technical documentation and website -- Compares existing documentation against the CNCF’s standards -- Recommends a program of key improvements with the largest return on investment +- Compares existing documentation against the CNCF's standards +- Recommends a program of key improvements with the largest return on + investment ### Scope of analysis The documentation discussed here includes the entire contents of the website, -the technical documentation, and documentation for contributors and users on the -helm-www GitHub repository. +the technical documentation, and documentation for contributors and users on +the helm-www GitHub repository. -The Helm website and documentation are written in Markdown and are compiled using the Docusaurus static -site generator with the theme-classic theme and served from the Netlify -platform. The site's code is stored on the helm-www GitHub repo. +The Helm website and documentation are written in Markdown and are compiled +using the Docusaurus static site generator with the theme-classic theme and +served from the Netlify platform. The site's code is stored on the helm-www +GitHub repo. #### In scope @@ -54,12 +57,13 @@ platform. The site's code is stored on the helm-www GitHub repo. #### Out of scope -- [helm/helm](https://github.com/helm/helm), [helm/community](https://github.com/helm/community), and other Helm subrepos +- [helm/helm](https://github.com/helm/helm), + [helm/community](https://github.com/helm/community), and other Helm subrepos ### How this document is organized -This document is divided into three sections that represent three major areas of -concern: +This document is divided into three sections that represent three major areas +of concern: - **Project documentation:** concerns documentation for users of the Helm software, aimed at people who intend to use the project software @@ -73,19 +77,20 @@ Each section begins with summary ratings based on a rubric with appropriate - **Comments**: observations about the existing documentation, with a focus on how it does or does not help Helm users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness of - the documentation. +- **Recommendations**: suggested changes that would improve the effectiveness + of the documentation. The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed -into a series of [issues] and entered as GitHub [issues](https://github.com/helm/helm-www/issues). +into a series of [issues] and entered as GitHub +[issues](https://github.com/helm/helm-www/issues). ### How to use this document -Readers interested only in actionable improvements should skip this document and -read the **[implementation] plan** and **[issues list]**. +Readers interested only in actionable improvements should skip this document +and read the **[implementation] plan** and **[issues list]**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining @@ -95,8 +100,8 @@ to their area of concern: - [Contributor documentation](#contributor-documentation) - [Website and documentation infrastructure](#website-and-infrastructure) -Examples of CNCF documentation that demonstrate the analysis criteria are linked -from the [criteria] specification. +Examples of CNCF documentation that demonstrate the analysis criteria are +linked from the [criteria] specification. #### Recommendations, requirements, and best practices @@ -105,23 +110,23 @@ and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from -the lexicon of [RFCs][rfc-spec], the changes described here should be understood -as "recommended" or "should" at the strongest, and "optional" or "may" in many -cases. Any "must" or "required" actions are clearly denoted as such, and pertain -to legal requirements such as copyright and licensing issues. +the lexicon of [RFCs][rfc-spec], the changes described here should be +understood as "recommended" or "should" at the strongest, and "optional" or +"may" in many cases. Any "must" or "required" actions are clearly denoted as +such, and pertain to legal requirements such as copyright and licensing issues. ## Project documentation Helm is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -| Criterion | [Rating (1-5)] | -| -------------------------- | -------------- | -| Information architecture | 2 - needs improvement | -| New user content | 2 - needs improvement | +| Criterion | [Rating (1-5)] | +| -------------------------- | ------------------------------ | +| Information architecture | 2 - needs improvement | +| New user content | 2 - needs improvement | | Content maintainability | 4 - meets or exceeds standards | -| Content creation processes | 2 - needs improvement | -| Inclusive language | 3 - meets standards | +| Content creation processes | 2 - needs improvement | +| Inclusive language | 3 - meets standards | ### Comments @@ -130,178 +135,340 @@ Documentation rubric. #### Information architecture -**High level conceptual/“About” content** +##### High level conceptual/"About" content -The Helm docs in general lack a high level overview that provides an introduction to the product, its use cases, user personas, and so on. +The Helm docs in general lack a high level overview that provides an +introduction to the product, its use cases, user personas, and so on. There is some level of project overview/conceptual content on these pages: -- The Using Helm page (https://helm.sh/docs/intro/using_helm) does include some conceptual information about the concepts of Helm charts, repositories, and releases -- The Introduction section (https://helm.sh/docs/intro/) includes information primarily for users of Helm charts (ie, no info for chart developers). It includes a quickstart guide that walks you through installing an example chart, a page on how to install Helm, a page with info about common Helm tasks like installing, upgrading, and working with repos, and a "cheat sheet" with quick references for common CLI commands. -- There is also some high level conceptual information in the "Topics" section of the docs. For example, Helm Architecture (https://helm.sh/docs/topics/architecture). -**Feature complete docs** +- The Using Helm page (https://helm.sh/docs/intro/using_helm) does include some + conceptual information about the concepts of Helm charts, repositories, and + releases -Overall, main Helm features are documented (like variables, template functions, hooks, and the Helm CLI). +- The Introduction section (https://helm.sh/docs/intro/) includes information + primarily for users of Helm charts (ie, no info for chart developers). It + includes a quickstart guide that walks you through installing an example + chart, a page on how to install Helm, a page with info about common Helm + tasks like installing, upgrading, and working with repos, and a "cheat sheet" + with quick references for common CLI commands. -But, there are several new features/breaking changes that need to be updated for Helm 4. For example: -- kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well (https://github.com/helm/helm/pull/13604) -- OCI install with digest (https://github.com/helm/helm-www/pull/1629) -- Multi document values files (https://github.com/helm/helm/pull/13655) -- Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) -- Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) +- There is also some high level conceptual information in the "Topics" section + of the docs. For example, Helm Architecture + (https://helm.sh/docs/topics/architecture). +##### Feature complete docs -**Step-by-step instructions** +Overall, main Helm features are documented (like variables, template functions, +hooks, and the Helm CLI). -The Helm docs don't really include tasks in the recommended "step-by-step" format. Instead, they tend to use descriptions of how a given features works, plus examples. For example, see the https://helm.sh/docs/howto/charts_tips_and_tricks/ page, which has information about how to do several tasks with Helm using paragraphs and examples. For example: - - The page on Installing Helm (https://helm.sh/docs/intro/install) is a good example of documenting one-step procedures - - Syncing Your Chart Reposiotry (https://helm.sh/docs/howto/chart_repository_sync_example) is close to a traditional step-by-step guide. It uses headings rather than numbered steps, but seems like it could easily be converted to a numbered list of steps. It also includes helpful prerequisites and examples. +But, there are several new features/breaking changes that need to be updated +for Helm 4. For example: - Note: While it's important for the Helm docs to use a step-by-step format for procedures where appropriate, because Helm charts are highly configurable/customizable, in many cases, it's probably more useful for chart developers to have several examples versus traditional step-by-step instructions +- kstatus watcher needs to be documented in the SDK docs and likely some + user-facing docs needed outside of the SDK docs as well + (https://github.com/helm/helm/pull/13604) -The Helm docs include some tutorials on workflows like creating different types of plugins using the different supported runtimes (eg, https://helm.sh/docs/plugins/developer/tutorial-cli-plugin). There are several other pages that use a tutorial-style format that walks users through a specific example in order to explain a given task or feature. For example: -- https://helm.sh/docs/chart_template_guide/accessing_files uses a variety of examples to explain different ways to create and access named templates -- https://helm.sh/docs/chart_template_guide/notes_files walks users through an example of adding a NOTES.txt for a chart +- OCI install with digest (https://github.com/helm/helm-www/pull/1629) -Tasks for key features are generally well-documented. As mentioned above, at a high level, the Helm docs would likely benefit from including more step-by-step how-tos/tutorials, but seems that the docs do include at least a few examples for each of the key Helm features. +- Multi document values files (https://github.com/helm/helm/pull/13655) -For the most part, tasks demonstrate atomicity and isolation of concerns, and are given relevant headings. There are some pages like "Using Helm" that would probably be better broken down into several smaller pages that users can see from the sidebar. Also, there are some places where there is extra info under a heading that one might not expect to find there. For example, under [Writing a Hook](https://helm.sh/docs/topics/charts_hooks#writing-a-hook), there is conceptual information about how hooks work, like that you can implement multiple hooks in a single resource or that multiple resources can be inplemented as the same type of hook. These are important details about how hooks work, but they are a bit hidden half way down a section whose heading uses a verb phrase. +- Allow signing multiple charts with single passphrase from stdin + (https://github.com/helm/helm/pull/30718) -**Happy path/common use cases** +- Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) + +##### Step-by-step instructions + +The Helm docs don't really include tasks in the recommended "step-by-step" +format. Instead, they tend to use descriptions of how a given features works, +plus examples. For example, see the +https://helm.sh/docs/howto/charts_tips_and_tricks/ page, which has information +about how to do several tasks with Helm using paragraphs and examples. For +example: + +- The page on Installing Helm (https://helm.sh/docs/intro/install) is a good + example of documenting one-step procedures + +- Syncing Your Chart Repository + (https://helm.sh/docs/howto/chart_repository_sync_example) is close to a + traditional step-by-step guide. It uses headings rather than numbered steps, + but seems like it could easily be converted to a numbered list of steps. It + also includes helpful prerequisites and examples. + +Note: While it's important for the Helm docs to use a step-by-step format for +procedures where appropriate, because Helm charts are highly +configurable/customizable, in many cases, it's probably more useful for chart +developers to have several examples versus traditional step-by-step +instructions. + +The Helm docs include some tutorials on workflows like creating different types +of plugins using the different supported runtimes (eg, +https://helm.sh/docs/plugins/developer/tutorial-cli-plugin). There are several +other pages that use a tutorial-style format that walks users through a +specific example in order to explain a given task or feature. For example: + +- https://helm.sh/docs/chart_template_guide/accessing_files uses a variety of + examples to explain different ways to create and access named templates + +- https://helm.sh/docs/chart_template_guide/notes_files walks users through an + example of adding a NOTES.txt for a chart + +Tasks for key features are generally well-documented. As mentioned above, at a +high level, the Helm docs would likely benefit from including more step-by-step +how-tos/tutorials, but seems that the docs do include at least a few examples +for each of the key Helm features. + +For the most part, tasks demonstrate atomicity and isolation of concerns, and +are given relevant headings. There are some pages like "Using Helm" that would +probably be better broken down into several smaller pages that users can see +from the sidebar. Also, there are some places where there is extra info under a +heading that one might not expect to find there. For example, under +[Writing a Hook](https://helm.sh/docs/topics/charts_hooks#writing-a-hook), +there is conceptual information about how hooks work, like that you can +implement multiple hooks in a single resource or that multiple resources can be +implemented as the same type of hook. These are important details about how +hooks work, but they are a bit hidden half way down a section whose heading +uses a verb phrase. + +##### Happy path/common use cases Helm has a few different happy paths depending on the user persona: -- Chart users needs to understand how to install helm, install/upgrade charts, work with chart repositories, and so on -- Chart developers need to know how to work with features like values files, template functions, chart hooks, and so on -For chart users, the "happy path" of initializing a chart repository, installing a chart, viewing release info for the chart, then uninstalling is documented in the Quickstart workflow. The Using Helm page also touches on each of the main tasks that a chart user would need to know about +- Chart users needs to understand how to install helm, install/upgrade charts, + work with chart repositories, and so on + +- Chart developers need to know how to work with features like values files, + template functions, chart hooks, and so on + +For chart users, the "happy path" of initializing a chart repository, +installing a chart, viewing release info for the chart, then uninstalling is +documented in the Quickstart workflow. The Using Helm page also touches on each +of the main tasks that a chart user would need to know about. + +As a chart developer, it's not very clear from looking at the docs sidebar if +there's a most common use case or "happy path" documented. The closest page to +this is [Charts](https://helm.sh/docs/topics/charts), which does include lots +of helpful info about the chart file structure, working with chart +dependencies, templates and values, and more. However, it's a lot of info in +one page, and it doesn't necessarily walk developers through how all these +pieces should fit together to create a release. + +##### Clear escalation path to get more help -As a chart developer, it's not very clear from looking at the docs sidebar if there's a most common use case or "happy path" documented. The closest page to this is [Charts](https://helm.sh/docs/topics/charts), which does include lots of helpful info about the chart file structure, working with chart dependencies, templates and values, and more. However, it's a lot of info in one page, and it doesn't necessarily walk developers through how all these pieces should fit together to create a release. +If the docs do not suffice, there are a couple places where an escalation path +is documented for users that need more help: -**Clear escalation path to get more help** +- The community section of the docs (which is pulled in from the Helm community + repository) includes most of the helpful info about troubleshooting. For + example, https://helm.sh/community/developers/#troubleshooting provides + information about working with the community and searching the existing + issues in the Helm repo to troubleshoot. -If the docs do not suffice, there are a couple places where an escalation path is documented for users that need more help: - - The community section of the docs (which is pulled in from the Helm community repository) includes most of the helpful info about troubleshooting. For example, https://helm.sh/community/developers/#troubleshooting provides information about working with the community and searching the existing issues in the Helm repo to troubleshoot. - - There are also some minimal FAQs here: https://helm.sh/docs/faq/. They include a few questions about installing and one question about uninstalling. It looks like this information is not really an "FAQ", but rather information about installing/uninstalling Helm that might have been documented under FAQs because it lacks a more permanent home. +- There are also some minimal FAQs here: https://helm.sh/docs/faq/. They + include a few questions about installing and one question about uninstalling. + It looks like this information is not really an "FAQ", but rather information + about installing/uninstalling Helm that might have been documented under FAQs + because it lacks a more permanent home. The Helm docs lack clear troubleshooting steps for different common tasks. -**API reference** +##### API reference API reference is here: https://pkg.go.dev/helm.sh/helm/v4 -**Content accuracy** +##### Content accuracy -In general, content is accurate. The main concern in terms of accuracy would be content that is out-of-date, particular when it comes to the latest Helm v4 docs. For example: -- There are several examples throughout the docs that use the Bitnami charts (ex: Quickstart and Using Helm pages). With the recent change from Broadcom, the images for those charts are no longer available free of charge, so these examples will need to be updated with new charts -- For the Helm v4 docs, there is a fair bit of out of date content. Some of the new features haven't been fully doc'd yet -- There's also several warnings "This page has not yet been updated for Helm 4." This content needs to be evaluated and updated +In general, content is accurate. The main concern in terms of accuracy would be +content that is out-of-date, particular when it comes to the latest Helm v4 +docs. For example: + +- There are several examples throughout the docs that use the Bitnami charts + (ex: Quickstart and Using Helm pages). With the recent change from Broadcom, + the images for those charts are no longer available free of charge, so these + examples will need to be updated with new charts + +- For the Helm v4 docs, there is a fair bit of out of date content. Some of the + new features haven't been fully doc'd yet + +- There's also several warnings "This page has not yet been updated for Helm + 4." This content needs to be evaluated and updated #### New user content -**Getting started content** +##### Getting started content -There is Getting Started section on the site homepage. It includes Helm download commands and a link to Artiact Hub where you can find Helm charts. It links users to the docs for more infomation (specifically, it links to the installing Helm and using Helm docs pages). +There is Getting Started section on the site homepage. It includes Helm +download commands and a link to Artifact Hub where you can find Helm charts. It +links users to the docs for more information (specifically, it links to the +installing Helm and using Helm docs pages). -In terms of “getting started” docs that are clearly labeled as such, there is both an "Introduction" section and a page named "Quickstart". However, the content in these sections is for chart users and does not include information that would be useful to chart developers just getting started. +In terms of "getting started" docs that are clearly labeled as such, there is +both an "Introduction" section and a page named "Quickstart". However, the +content in these sections is for chart users and does not include information +that would be useful to chart developers just getting started. -After completing the quickstart or reading the introduction section, there's no clear info about what the user should do next. In general, it's hard to grock the most common use cases for Helm from looking at the docs table of contents, so it's not clear the user would be able to intuit how they could use Helm. +After completing the quickstart or reading the introduction section, there's no +clear info about what the user should do next. In general, it's hard to scan to +the docs to quickly learn the most common use cases for Helm, so it's not clear +the user would be able to intuit how they could use Helm. -This Next Steps page in the Chart Template Guide does provide a good example of pointing chart developers to more information about chart development: https://helm.sh/docs/chart_template_guide/wrapping_up +This Next Steps page in the Chart Template Guide does provide a good example of +pointing chart developers to more information about chart development: +https://helm.sh/docs/chart_template_guide/wrapping_up -**Step-by-step install procedures** +##### Step-by-step install procedures -The installation steps for Helm are really just single comamnds (ie, one-step procedures) for a variety of different install environments: https://helm.sh/docs/intro/install +The installation steps for Helm are really just single commands (ie, one-step +procedures) for a variety of different install environments: +https://helm.sh/docs/intro/install -These install docs include code blocks that have a "copy" button which allows them to be easily copy-pasted. +These install docs include code blocks that have a "copy" button which allows +them to be easily copy-pasted. #### Content maintainability & site mechanics -**Search** +##### Search The documentation is searchable (it uses Algolia DocSearch). -**Localization/i18n** +##### Localization/i18n + +The Helm website is localized. Helm.sh uses Docusaurus' built-in +localization/translations feature to allow users to toggle between different +languages. The localization process documented here: +https://helm.sh/community/localization. + +##### Versioning + +The versioning process for the Helm website is documented in the readme: +https://github.com/helm/helm-www/blob/main/README.md#versioning: -The Helm website is localized. Helm.sh uses Docusaurus' built-in localization/translations feature to allow users to toggle between different languages. The localization process documented here: https://helm.sh/community/localization. +- Helm.sh releases a new version of the docs with each major release -**Versioning** +- Helm.sh uses the version number in the URL path for non-latest versions of + the product (the latest version is served at the main /docs/ path with no + version number) -The versioning process for the Helm website is documented in the readme: https://github.com/helm/helm-www/blob/main/README.md#versioning: - - Helm.sh releases a new version of the docs with each major release - - Helm.sh uses the version number in the URL path for non-latest versions of the product (the latest version is served at the main /docs/ path with no version number) - - Version labels on the site are updated to use the latest minor/patch version +- Version labels on the site are updated to use the latest minor/patch version #### Content creation processes -**Contribution process for documentation** +##### Contribution process for documentation -Documentation contribution how-tos are documented in the helm-www README and in the Community section (eg https://helm.sh/community/localization) +Documentation contribution how-tos are documented in the helm-www README and in +the Community section (eg https://helm.sh/community/localization) -However, there isn't a clearly documented ongoing process for how often PRs/issues get reviewed, requirements for docs PRs in order to be approved, a style guide, issue triage plan, etc. +However, there isn't a clearly documented ongoing process for how often +PRs/issues get reviewed, requirements for docs PRs in order to be approved, a +style guide, issue triage plan, etc. -**Code release process** +##### Code release process -The code release process does account for documentation creation and updates in that PR include a checkbox for "this PR includes documentation", if applicable. +The code release process does account for documentation creation and updates in +that PR include a checkbox for "this PR includes documentation", if applicable. -However, there doesn't seem to be a requirement that a documentation PR exists for a code change (if needed) before a code change is approved is merged. +However, there doesn't seem to be a requirement that a documentation PR exists +for a code change (if needed) before a code change is approved is merged. -**Docs PR review/approval** +##### Docs PR review/approval -Maintainers of the helm-www repo and core project maintainers can review and approve docs PRs. +Maintainers of the helm-www repo and core project maintainers can review and +approve docs PRs. -**Website owners** +##### Website owners -Maintainers are clearly listed in the OWNERS file https://github.com/helm/helm-www/blob/main/OWNERS. Maintiners were recently updated to add/remove as needed, but there is not an ongoing process for reviewing and updating the list of maintainers. +Maintainers are clearly listed in the OWNERS file +https://github.com/helm/helm-www/blob/main/OWNERS. Maintainers were recently +updated to add/remove as needed, but there is not an ongoing process for +reviewing and updating the list of maintainers. #### Inclusive language -There do not appear to be any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website. +There do not appear to be any customer-facing utilities, endpoints, class +names, or feature names that use non-recommended words as documented by the +[Inclusive Naming Initiative](https://inclusivenaming.org) website. -The docs do occassionally use language like "simple", "easy", etc. Example: https://helm.sh/docs/topics/registries/#migrating-from-chart-repos +The docs do occasionally use language like "simple", "easy", etc. Example: +https://helm.sh/docs/topics/registries/#migrating-from-chart-repos ### Recommendations #### Information architecture -It will be helpful to find greater specificity in the naming strategy for categories. With the current naming of the sections in the sidebar, it's not clear to docs users or contributors how the pages are grouped, and what types of info should go where. Many sections are named by content type (how-to, topics, faqs, best practices). This is fine, but can be challenging to maintain and find content when it's not clear what qualifies as each content type (for example, Topics has become a large catch-all category). By using more specific categories that align with a given product area or use case, it'll be more obvious where info can be found. +It will be helpful to find greater specificity in the naming strategy for +categories. With the current naming of the sections in the sidebar, it's not +clear to docs users or contributors how the pages are grouped, and what types +of info should go where. Many sections are named by content type (how-to, +topics, FAQs, best practices). This is fine, but can be challenging to maintain +and find content when it's not clear what qualifies as each content type (for +example, Topics has become a large catch-all category). By using more specific +categories that align with a given product area or use case, it'll be more +obvious where info can be found. -Additionally, content throughout should be reviewed to see where there is redundant content that can be condensed. For example, lots of the pages in Topics, FAQs, Introduction, Best Practices feels out-of-date or redundant with other pages +Additionally, content throughout should be reviewed to see where there is +redundant content that can be condensed. For example, lots of the pages in +Topics, FAQs, Introduction, Best Practices feels out-of-date or redundant with +other pages. -Finally, procedures should be converted to step-by-step instructions for better readability. +Finally, procedures should be converted to step-by-step instructions for better +readability. #### New user content -The site could use a more cleraly labeled "getting started" section, with guides for all main user personas (both chart users and chart developers). For example, a quick start that shows how to create and release a simple chart and/or a page that explains that chart dev "happy path", including all the main tasks a chart developer should consider as part of creating and publishing a chart for their app. Could probably use lots of the content in Using Helm to create getting started info for chart developers +The site could use a more clearly labeled "getting started" section, with +guides for all main user personas (both chart users and chart developers). For +example, a quick start that shows how to create and release a simple chart +and/or a page that explains that chart dev "happy path", including all the main +tasks a chart developer should consider as part of creating and publishing a +chart for their app. Could probably use lots of the content in Using Helm to +create getting started info for chart developers. #### Content maintainability & site mechanics -Search, locaization, and versioning functionality all looks good/is useable on the site. +Search, localization, and versioning functionality all looks good/is useable on +the site. -Helm.sh is in need of a better process for reviewing and accepting localized documentation changes (including adding a new locale). There are several open PRs from people adding translations to the site, but not a good process for determining how those get reviewed, how drift is tracked/updated, and so on. A good example of this is here: https://opentelemetry.io/docs/contributing/localization/. +Helm.sh is in need of a better process for reviewing and accepting localized +documentation changes (including adding a new locale). There are several open +PRs from people adding translations to the site, but not a good process for +determining how those get reviewed, how drift is tracked/updated, and so on. A +good example of this is here: +https://opentelemetry.io/docs/contributing/localization/. #### Content creation processes -The contributors docs could be better centralized and easier to search, maybe in a "Contribute to the Docs" section. Currently, the contributor info is spread across the README, [CONTRIBUTING](https://github.com/paigecalvert/helm-www/blob/main/CONTRIBUTING.md), and the Community section, which makes it a bit harder to find, and harder to tell when it's out of date. +The contributors docs could be better centralized and easier to search, maybe +in a "Contribute to the Docs" section. Currently, the contributor info is +spread across the README, +[CONTRIBUTING](https://github.com/paigecalvert/helm-www/blob/main/CONTRIBUTING.md), +and the Community section, which makes it a bit harder to find, and harder to +tell when it's out of date. -Also, the team could make docs more "part of the definition of done" for new features. For example, when a docs update is needed, creating the docs PR could be required before a new feature PR to be merged. This would help ensure that the docs stay up to date. +Also, the team could make docs more "part of the definition of done" for new +features. For example, when a docs update is needed, creating the docs PR could +be required before a new feature PR to be merged. This would help ensure that +the docs stay up to date. #### Inclusive language Review the docs for terms like "simply" and "easy" and remove them. -Helm.sh could also choose an existing, industry-accepted style guide to point contributors to, including a link to the inclusive language website. This would help maintain inclusive, clear word choice throughout. +Helm.sh could also choose an existing, industry-accepted style guide to point +contributors to, including a link to the inclusive language website. This would +help maintain inclusive, clear word choice throughout. ## Contributor documentation Helm is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -| Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | -| Communication methods documented | 3 - meets standards | +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | --------------------- | +| Communication methods documented | 3 - meets standards | | Beginner friendly issue backlog | 2 - needs improvement | -| “New contributor” getting started content | 3 - meets standards | -| Project governance documentation | 3 - meets standards | +| "New contributor" getting started content | 3 - meets standards | +| Project governance documentation | 3 - meets standards | ### Comments @@ -310,77 +477,102 @@ Contributor Documentation rubric. #### Communication methods documented -**Slack and dev meetings** +##### Slack and dev meetings -The Helm Slack channels are prominently linked in the Join the Community section on the landing page. This section also has info about upcoming events, weekly developer standups (with info on how to join), and more. Additionally, the Community section of the website (https://helm.sh/community) also includes this information. +The Helm Slack channels are prominently linked in the Join the Community +section on the landing page. This section also has info about upcoming events, +weekly developer stand-ups (with info on how to join), and more. Additionally, +the Community section of the website (https://helm.sh/community) also includes +this information. -**GitHub links** +##### GitHub links -Users can find direct links to the Helm GitHub organization/repositories in a couple ways: -- There are links on the site homepage, in the community section, and in the footer to the main Helm github -- There's an edit this page link on every docs page that allows the user to open it in the helm-www repo in github +Users can find direct links to the Helm GitHub organization/repositories in a +couple ways: -**Mailing lists** - -Mailing lists are documented here: https://helm.sh/community/communication/#mailing-lists +- There are links on the site homepage, in the community section, and in the + footer to the main Helm github + +- There's an edit this page link on every docs page that allows the user to + open it in the helm-www repo in github + +##### Mailing lists + +Mailing lists are documented here: +https://helm.sh/community/communication/#mailing-lists #### Beginner friendly issue backlog -Docs issues are not very well triaged. There are nearly 100 open docs issues, many irrelevant to the new site. There is also no clear traige plan or timelines in place for addressing issues or reviewing them for freshness. +Docs issues are not very well triaged. There are nearly 100 open docs issues, +many irrelevant to the new site. There is also no clear triage plan or +timelines in place for addressing issues or reviewing them for freshness. -There is a “good first issue” label, which new contributors can use to make code or documentation contributions. +There is a "good first issue" label, which new contributors can use to make +code or documentation contributions. -In general, issues are well-documented and include helpful descriptions beyond just a title. There doesn't seem to be an issue template. +In general, issues are well-documented and include helpful descriptions beyond +just a title. There doesn't seem to be an issue template. #### New contributor getting started content -**Community docs** +##### Community docs -The website has a community section here: https://helm.sh/community. This is automatically pulled in from the helm/community repo using a plugin. +The website has a community section here: https://helm.sh/community. This is +automatically pulled in from the helm/community repo using a plugin. -**Docs for first-time contributors** +##### Docs for first-time contributors + +Helm.sh has the following content that does a good job of providing info for +first-time contributors: -Helm.sh has the following content that does a good job of providing info for first-time contributors: - https://helm.sh/community/developers + - https://helm.sh/community/#your-first-contribution -Also, while there's nothing specifically labeled "get help" on the site, there's plenty of places where the slack channels, dev meetings, etc are listed for users +Also, while there's nothing specifically labeled "get help" on the site, +there's plenty of places where the slack channels, dev meetings, etc are listed +for users. #### Project governance documentation -Is Project governance clearly is documented here: https://helm.sh/community/governance/ +Is Project governance clearly is documented here: +https://helm.sh/community/governance/ ### Recommendations #### Beginner friendly issue backlog -Improved standards/practices around regular issue triage and maintaining issue freshness could help make the issue backlog a little easier to navigate. +Improved standards/practices around regular issue triage and maintaining issue +freshness could help make the issue backlog a little easier to navigate. #### New contributor getting started content -While new contributor docs are well documented, it also couldn't hurt to add a heading (in the Community docs, perhaps) that includes the terms "troubleshooting" or "get help", in case people search to website for those terms. +While new contributor docs are well documented, it also couldn't hurt to add a +heading (in the Community docs, perhaps) that includes the terms +"troubleshooting" or "get help", in case people search to website for those +terms. ## Website and infrastructure Helm is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. -| Criterion | [Rating (1-5)] | -| ------------------------------------------- | -------------- | -| Single-source for all files | 3 - meets standards | -| Meets min website req. (for maturity level) | 3 - meets standards | +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | ------------------------------ | +| Single-source for all files | 3 - meets standards | +| Meets min website req. (for maturity level) | 3 - meets standards | | Usability, accessibility, and design | 4 - meets or exceeds standards | | Branding and design | 4 - meets or exceeds standards | -| Case studies/social proof | 1 - not present | -| SEO, Analytics, and site-local search | 3 - meets standards | -| Maintenance planning | 3 - meets standards | -| A11y plan & implementation | 3 - meets standards | -| Mobile-first plan & impl. | 3 - meets standards | -| HTTPS access & HTTP redirect | 3 - meets standards | -| Google Analytics 4 for production only | 1 - not present | -| Indexing allowed for production server only | 3 - meets standards | -| Intra-site / local search | 3 - meets standards | -| Account custodians are documented | 2 - needs improvement | +| Case studies/social proof | 1 - not present | +| SEO, Analytics, and site-local search | 3 - meets standards | +| Maintenance planning | 3 - meets standards | +| A11y plan & implementation | 3 - meets standards | +| Mobile-first plan & impl. | 3 - meets standards | +| HTTPS access & HTTP redirect | 3 - meets standards | +| Google Analytics 4 for production only | 1 - not present | +| Indexing allowed for production server only | 3 - meets standards | +| Intra-site / local search | 3 - meets standards | +| Account custodians are documented | 2 - needs improvement | ### Comments @@ -389,15 +581,24 @@ and documentation infrastructure rubric. #### Single-source requirement -Nearly all website pages reside in a single repo (helm/helm-www). The exception to this is the Community section of the website, which pulls in docs from the helm/community repo using a plugin. This is documented in the readme: https://github.com/helm/helm-www?tab=readme-ov-file#community-documentation. Additionally, the "Edit this page" link at the bottom of the community pages properly sends users to the page source in the helm/community repo to prevent users from accidentally editing the wrong source. +Nearly all website pages reside in a single repo (helm/helm-www). The exception +to this is the Community section of the website, which pulls in docs from the +helm/community repo using a plugin. This is documented in the readme: +https://github.com/helm/helm-www?tab=readme-ov-file#community-documentation. +Additionally, the "Edit this page" link at the bottom of the community pages +properly sends users to the page source in the helm/community repo to prevent +users from accidentally editing the wrong source. -The way the community section is set up, there is no need for maintainers to keep multiple versions of the community docs up-to-date/in sync. And, Helm maintainers have indicated that pulling in the community doc in this way is useful for making the information more findable for users. +The way the community section is set up, there is no need for maintainers to +keep multiple versions of the community docs up-to-date/in sync. And, Helm +maintainers have indicated that pulling in the community doc in this way is +useful for making the information more findable for users. #### Minimal website requirements Listed here are the minimal website requirements for projects based on their -[maturity level][maturity-level], either incubating or graduated. (These are the -only two levels for which a tech docs analysis can be requested.) +[maturity level][maturity-level], either incubating or graduated. (These are +the only two levels for which a tech docs analysis can be requested.) @@ -417,71 +618,104 @@ only two levels for which a tech docs analysis can be requested.) #### Usability, accessibility and devices -**Usability / mobile experience** +##### Usability / mobile experience -The website usable from mobile (doc pages are readable, and all website features are accessible from mobile including the top-nav, site search and in-page table of contents) +The website usable from mobile (doc pages are readable, and all website +features are accessible from mobile including the top-nav, site search and +in-page table of contents). -**Accessibility** +##### Accessibility -A Chrome Lighthouse audit on the helm.sh site gives a score of 94/100 for accessibility. It reports that the light blue link color (such as for the word Kubernetes on the landing page subtitle) is not high enough contrast for color-impaired readers. It also reports that there are some links that use only color to differentiate them from the surrounding text. +A Chrome Lighthouse audit on the helm.sh site gives a score of 94/100 for +accessibility. It reports that the light blue link color (such as for the word +Kubernetes on the landing page subtitle) is not high enough contrast for +color-impaired readers. It also reports that there are some links that use only +color to differentiate them from the surrounding text. -Did not test the text-to-speech, but the amount of code and special characters in the text generally means that text-to-speech is not likely to be a good experience for users. +Did not test the text-to-speech, but the amount of code and special characters +in the text generally means that text-to-speech is not likely to be a good +experience for users. #### Branding and design -There is an easily recognizable brand for the project (logo + color scheme) that is used across the website consistently. The website's typography is consistent and easy to read. The only exception is that the font used for headings can be somewhat difficult to read for some of the letters. +There is an easily recognizable brand for the project (logo + color scheme) +that is used across the website consistently. The website's typography is +consistent and easy to read. The only exception is that the font used for +headings can be somewhat difficult to read for some of the letters. #### Case studies/social proof -There is a logo wall of participating organizations featured at the bottom of the landing page (called "Supporters"). There is not a list of Helm users, but perhaps the supporters are also the users that would be listed +There is a logo wall of participating organizations featured at the bottom of +the landing page (called "Supporters"). There is not a list of Helm users, but +perhaps the supporters are also the users that would be listed. -There do not appear to be any case studies or testimonials available for the project that are documented on the website. I do see Helm case studies on the CNCF website, but not sure how recent or relevant these are: https://www.cncf.io/case-studies/?_sft_lf-project=helm +There do not appear to be any case studies or testimonials available for the +project that are documented on the website. I do see Helm case studies on the +CNCF website, but not sure how recent or relevant these are: +https://www.cncf.io/case-studies/?_sft_lf-project=helm #### SEO, Analytics and site-local search -**Analytics** +##### Analytics -Analytics is not set up for the site. +Analytics is not set up for the site. -**SEO, Indexing, and Search** +##### SEO, Indexing, and Search -Local intra-site search is available from the website. Search is powered by Algolia DocSearch. The production site is well-indexed thanks to a built-in Algolia config for Docusaurus site, and is reindexed daily (this schedule is controlled by an algolia crawler setting). +Local intra-site search is available from the website. Search is powered by +Algolia DocSearch. The production site is well-indexed thanks to a built-in +Algolia config for Docusaurus site, and is reindexed daily (this schedule is +controlled by an algolia crawler setting). -**Account custodians** +##### Account custodians -The current custodian(s) of the following Algolia account is not specifically documented, but the repo does have an OWNERS file. +The current custodian(s) of the following Algolia account is not specifically +documented, but the repo does have an OWNERS file. #### Maintenance planning -**Website tooling** +##### Website tooling -The website uses Docusaurus, which has a robust open source community and is actively maintained. Before Helm.sh was migrated to Docusaurus, the migration and tooling was discussed with the CNCF tech docs team to make sure it was recommended. +The website uses Docusaurus, which has a robust open source community and is +actively maintained. Before Helm.sh was migrated to Docusaurus, the migration +and tooling was discussed with the CNCF tech docs team to make sure it was +recommended. -**Website maintainers** +##### Website maintainers -There is no indication that the project is actively cultivating website maintainers from the community. +There is no indication that the project is actively cultivating website +maintainers from the community. -**Build times** +##### Build times -Build times can be quite long (10+ mins). This is because Docusaurus builds a separate site for each locale, and Helm.sh has several locales. There is a script in the repo that is designed to use the Docusaurus cache to reduce build times (particularly useful for more quickly generating previews on PRs). This script tends to have varied results, but can reduce build times down to a reasonable 1-3 mins. +Build times can be quite long (10+ mins). This is because Docusaurus builds a +separate site for each locale, and Helm.sh has several locales. There is a +script in the repo that is designed to use the Docusaurus cache to reduce build +times (particularly useful for more quickly generating previews on PRs). This +script tends to have varied results, but can reduce build times down to a +reasonable 1-3 mins. #### Other -The website is accessible via HTTPS and requests using HTTP are properly redirected to the HTTPS URLs. +The website is accessible via HTTPS and requests using HTTP are properly +redirected to the HTTPS URLs. ### Recommendations #### Case studies/social proof -Could add a link to case studies on the landing page and/or prioritize writing and publishing case studies in the blog +Could add a link to case studies on the landing page and/or prioritize writing +and publishing case studies in the blog. #### SEO, Analytics and site-local search -Add analytics to the production server (could use Google Analytics (GA) 4), and ensure that 404 reports are collected and tracked using the analytics service. +Add analytics to the production server (could use Google Analytics (GA) 4), and +ensure that 404 reports are collected and tracked using the analytics service. #### Maintenance planning -Consider troubleshooting the existing script to see why it inconsistently reduces build times. +Consider troubleshooting the existing script to see why it inconsistently +reduces build times. #### References and notes @@ -498,8 +732,7 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./helm-implementation.md [issues list]: ./helm-issues-list.md -[project-doc-website]: https://helm.sh/docs/ [project-website]: https://helm.sh/ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 -[website guidelines]: ../../website-guidelines-checklist.md \ No newline at end of file +[website guidelines]: ../../website-guidelines-checklist.md diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/0016-helm/helm-implementation.md index f8d4dab..99cda79 100644 --- a/analyses/0016-helm/helm-implementation.md +++ b/analyses/0016-helm/helm-implementation.md @@ -1,14 +1,15 @@ --- title: Implementing Helm Doc Improvements tags: [Helm] +cSpell:ignore: kstatus unreviewed --- ## Introduction -This document provides actionable suggestions for improving the Helm -technical documentation. +This document provides actionable suggestions for improving the Helm technical +documentation. For an analysis and general discussion of recommendations on Helm technical documentation, see [analysis.md](helm-analysis.md). @@ -28,136 +29,216 @@ such, and pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: -> AUTHOR NOTE: Provide a summary or outline of the recommendations. Depending on -> the analysis findings, recommended actions might be organized into two or -> three high-level items that contain multiple actions, or might just be a list -> of independent changes. For examples, see a completed implementation plan such -> as 0008-Backstage or 0010-etcd. - ## Reorganize the main docs sidebar -As is, it is difficult for users to find information in the main docs sidebar. Some of the categories seek to group information by content type (How-To and Topics), while other categories group content by the specific product area (Chart Template Guide and Plugins). This inconsistency makes it difficult to intuit where the info you want might be located. It also makes it harder for docs contributors to decide where to situate a new page. +As is, it is difficult for users to find information in the main docs sidebar. +Some of the categories seek to group information by content type (How-To and +Topics), while other categories group content by the specific product area +(Chart Template Guide and Plugins). This inconsistency makes it difficult to +intuit where the info you want might be located. It also makes it harder for +docs contributors to decide where to situate a new page. + +The overall organization could be much improved by following a more consistent +pattern: -The overall organization could be much improved by following a more consistent pattern: - Include clearly labeled intro/new user content at the top -- At the highest level, group content by product area (for example, some product areas might be plugins, charts, and chart repositories) -- Within each product area, add concepts and tasks for the different user personas/use cases. For example, for charts, there need to be docs for users installing and using charts, as well as for users developing and releasing charts -- Consider pulling out reference material like CLI docs or info about policies to the top level, unassociated with a specific product area -Here is a proposed sidebar based on the above (note that this proposal attempts to keep existing pages intact as much as possible to make this easier to implement): +- At the highest level, group content by product area (for example, some product + areas might be plugins, charts, sdk) + +- Within each product area, add concepts and tasks for the different user + personas/use cases (chart users, developers, and distributors) + +- Reference material like CLI docs can be at top level, unassociated with a + specific product area + +Here is a proposed sidebar based on the above (note that this proposal attempts +to keep existing pages intact as much as possible to make this easier to +implement): - [Docs Home](https://helm.sh/docs/) - Helm 4 - What's New? (https://helm.sh/docs/overview) - [Full Changelog](https://helm.sh/docs/changelog) - Introduction - - Overview (A new Helm Overview page. Use the existing content in [Helm Architecture](https://helm.sh/docs/topics/architecture) and add content from [Three Big Concepts](https://helm.sh/docs/intro/using_helm#three-big-concepts) in _Using Helm_) + - Overview (A new Helm Overview page. Use the existing content in + [Helm Architecture](https://helm.sh/docs/topics/architecture) and add + content from + [Three Big Concepts](https://helm.sh/docs/intro/using_helm#three-big-concepts) + in _Using Helm_) - [Quickstart](https://helm.sh/docs/intro/quickstart) - [Installing Helm](https://helm.sh/docs/intro/install) - - [Kubernetes Distribution Guide](https://helm.sh/docs/topics/kubernetes_distros) + - Kubernetes Compatibility + - [Supported Kubernetes Distributions](https://helm.sh/docs/topics/kubernetes_distros) + - [Supported Kubernetes Versions](from + https://helm.sh/docs/topics/version_skew) - [Glossary](https://helm.sh/docs/glossary/) -- Install and Use Charts - - [Using Helm](https://helm.sh/docs/intro/using_helm) - - [Cheat Sheet](https://helm.sh/docs/intro/CheatSheet) - - Post Rendering (from https://helm.sh/docs/topics/advanced#post-rendering. Recommend breaking up "Advanced Helm Techniques" into two pages: Post-Rendering and Configure Store Backends. The title "Advanced Helm Techniques" makes it hard for users to guess what might be in it) - - Configure Storage Backends (from https://helm.sh/docs/topics/advanced#storage-backends) - - [Permissions management for SQL storage backend](https://helm.sh/docs/topics/permissions_sql_storage_backend) - - [Helm Provenance and Integrity](https://helm.sh/docs/topics/provenance) - - [Role-based Access Control](https://helm.sh/docs/topics/rbac) -- Develop Charts - - [Charts](https://helm.sh/docs/topics/charts) (eventually, this page could probably be broken out into smaller pages) - - [Chart Hooks](https://helm.sh/docs/topics/charts_hooks) - - [Chart Tests](https://helm.sh/docs/topics/chart_tests) - - [Library Charts](https://helm.sh/docs/topics/library_charts) - - Chart Values and Templates - - [most of the existing pages under [Chart Template Guide](https://helm.sh/docs/chart_template_guide/)] - - [The .helmignore file](https://helm.sh/docs/chart_template_guide/helm_ignore_file) - - [Creating a NOTES.txt File](https://helm.sh/docs/chart_template_guide/notes_files) - - Chart Development Best Practices - - [Chart Development Tips and Tricks](https://helm.sh/docs/howto/charts_tips_and_tricks) - - [other existing bets practices pages] -- Release Charts - - [The Chart Repository Guide](https://helm.sh/docs/topics/chart_repository) - - [Use OCI-based registries](https://helm.sh/docs/topics/registries) - - [Syncing Your Chart Repository](https://helm.sh/docs/howto/chart_repository_sync_example) - - [Chart Releaser Action to Automate GitHub Page Charts](https://helm.sh/docs/howto/chart_releaser_action) -- Use and Develop Plugins +- Charts + - Overview (main overview of Helm charts) + - Installing Charts (topics for the chart user persona) + - [Using Helm](https://helm.sh/docs/intro/using_helm) + - [Cheat Sheet](https://helm.sh/docs/intro/CheatSheet) + - Post Rendering (from https://helm.sh/docs/topics/advanced#post-rendering. + Recommend breaking up "Advanced Helm Techniques" into two pages: + Post-Rendering and Configure Store Backends. The title "Advanced Helm + Techniques" makes it hard for users to guess what might be in it) + - [Helm Provenance and Integrity](https://helm.sh/docs/topics/provenance) + - [Role-based Access Control](https://helm.sh/docs/topics/rbac) + - Developing Charts + - [Charts](https://helm.sh/docs/topics/charts) (eventually, this page could + probably be broken out into smaller pages) + - [Chart Hooks](https://helm.sh/docs/topics/charts_hooks) + - [Chart Tests](https://helm.sh/docs/topics/chart_tests) + - [Library Charts](https://helm.sh/docs/topics/library_charts) + - Chart Values and Templates + - [most of the existing pages under + [Chart Template Guide](https://helm.sh/docs/chart_template_guide/)] + - [The .helmignore file](https://helm.sh/docs/chart_template_guide/helm_ignore_file) + - [Creating a NOTES.txt File](https://helm.sh/docs/chart_template_guide/notes_files) + - Chart Development Best Practices + - [Chart Development Tips and Tricks](https://helm.sh/docs/howto/charts_tips_and_tricks) + - [other existing bets practices pages] + - Distributing Charts + - [info for chart distributors] +- Plugins - [Overview](https://helm.sh/docs/plugins/overview) - [Using Plugins](https://helm.sh/docs/plugins/user/) - [Developing Plugins](https://helm.sh/docs/plugins/developer/) - - [existing tutorials] +- Storage + - Overview (overview of storage) + - Packaging + - [The Chart Repository Guide](https://helm.sh/docs/topics/chart_repository) + - [Use OCI-based registries](https://helm.sh/docs/topics/registries) + - [Syncing Your Chart Repository](https://helm.sh/docs/howto/chart_repository_sync_example) + - [Chart Releaser Action to Automate GitHub Page Charts](https://helm.sh/docs/howto/chart_releaser_action) + - Release Data + - Configure Storage Backends (from + https://helm.sh/docs/topics/advanced#storage-backends) + - [Permissions management for SQL storage backend](https://helm.sh/docs/topics/permissions_sql_storage_backend) - [Helm Commands](https://helm.sh/docs/helm/) - [Go SDK](https://helm.sh/docs/sdk/) -- Policies - - [Release Schedule Policy](https://helm.sh/docs/topics/release_policy) - - [Helm Version Support Policy](https://helm.sh/docs/topics/version_skew) ## Add a technical/conceptual overview of Helm -Put architecture, operating principles, and other conceptual explanations in a high-level technical overview. +Put architecture, operating principles, and other conceptual explanations in a +high-level technical overview. -There is some existing content in the site that can probably be used to build this overview, particularly in [Helm Architecture](https://helm.sh/docs/topics/architecture). The goal of this new overview would be to give new users a good foundation to get started with Helm, including an understanding of the most common use cases, the typical user personas, and the primary concepts/terms to know. +There is some existing content in the site that can probably be used to build +this overview, particularly in +[Helm Architecture](https://helm.sh/docs/topics/architecture). The goal of this +new overview would be to give new users a good foundation to get started with +Helm, including an understanding of the most common use cases, the typical user +personas, and the primary concepts/terms to know. ## Prune out-of-date content -There are several pages in the docs that are likely out-of-date or otherwise no longer relevant. For example: -- "FAQs" https://helm.sh/docs/faq/installing and https://helm.sh/docs/faq/uninstalling +There are several pages in the docs that are likely out-of-date or otherwise no +longer relevant. For example: + +- "FAQs" https://helm.sh/docs/faq/installing and + https://helm.sh/docs/faq/uninstalling + - Best practices section: https://helm.sh/docs/chart_best_practices/ + - Tips and tricks: https://helm.sh/docs/howto/charts_tips_and_tricks -For each of these pages/section, if possible, prefer distributing the content across other existing pages so that these pages might be deleted. For example, could the RBAC best practices listed at https://helm.sh/docs/chart_best_practices/rbac be instead incorporated into the existing page on [Role-Based Access Control](https://helm.sh/docs/topics/rbac)? +For each of these pages/section, if possible, prefer distributing the content +across other existing pages so that these pages might be deleted. For example, +could the RBAC best practices listed at +https://helm.sh/docs/chart_best_practices/rbac be instead incorporated into the +existing page on [Role-Based Access Control](https://helm.sh/docs/topics/rbac)? -Alternatively, if the content is still important and doesn't fit well elsewhere in the docs, make the necessary updates so that it is up-to-date and accurate. +Alternatively, if the content is still important and doesn't fit well elsewhere +in the docs, make the necessary updates so that it is up-to-date and accurate. ## Finish the Helm v4 docs ### Document all the new features released with Helm 4 -Make sure that all the Helm 4 features, improvements, and fixes are documented. For example: -- kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well (https://github.com/helm/helm/pull/13604) +Make sure that all the Helm 4 features, improvements, and fixes are documented. +For example: + +- kstatus watcher needs to be documented in the SDK docs and likely some + user-facing docs needed outside of the SDK docs as well + (https://github.com/helm/helm/pull/13604) + - OCI install with digest (https://github.com/helm/helm-www/pull/1629) + - Multi document values files (https://github.com/helm/helm/pull/13655) -- Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) + +- Allow signing multiple charts with single passphrase from stdin + (https://github.com/helm/helm/pull/30718) + - Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) ### Review and update all the pages with the "This page has not yet been updated for Helm 4" warning -This warning was added to several pages in the Helm 4 docs to indicate that they've not yet been updated: +This warning was added to several pages in the Helm 4 docs to indicate that +they've not yet been updated: -"This page has not yet been updated for Helm 4. Some of the content might be inaccurate or not applicable to Helm 4. For more information about the Helm 4 new features, improvements, and breaking changes, see Helm 4 Overview." +"This page has not yet been updated for Helm 4. Some of the content might be +inaccurate or not applicable to Helm 4. For more information about the Helm 4 +new features, improvements, and breaking changes, see Helm 4 Overview." -Review all the pages where this warning appears, and review them to make any necessary updates. Then, remove the warning. +Review all the pages where this warning appears, and review them to make any +necessary updates. Then, remove the warning. ## Rewrite tasks as step-by-step procedures -CNCF strongly recommends that tasks and procedures are written as step-by-step instructions. For example: +CNCF strongly recommends that tasks and procedures are written as step-by-step +instructions. For example: ```mdx To do [task]: + 1. Do the first step. 1. Do the second step. ``` -This is also an industry-standard for technical documentation (See the Google Developer Docs style guide https://developers.google.com/style/procedures) +This is also an industry-standard for technical documentation (See the Google +Developer Docs style guide https://developers.google.com/style/procedures) -The Helm docs tend not to use step-by-step instructions for tasks and procedures. This is not ideal because it can cause conpetual/procedural/reference content to be inadvertently blended together, which makes information less findable to users. For users looking to accomplish a task, it can be challenging to weed through paragraphs. +The Helm docs tend not to use step-by-step instructions for tasks and +procedures. This is not ideal because it can cause +conceptual/procedural/reference content to be inadvertently blended together, +which makes information less findable to users. For users looking to accomplish +a task, it can be challenging to weed through paragraphs. -To improve the docs user experience, all tasks that are documented in the Helm docs should be reformatted or rewritten so that they use numbered steps. For example, each of the headings in https://helm.sh/docs/howto/chart_repository_sync_example could be converted to a numbered step in an ordered list. Assigning numbers to each item would make it immediately clearer that this is a prcedure that can be followed in order. +To improve the docs user experience, all tasks that are documented in the Helm +docs should be reformatted or rewritten so that they use numbered steps. For +example, each of the headings in +https://helm.sh/docs/howto/chart_repository_sync_example could be converted to a +numbered step in an ordered list. Assigning numbers to each item would make it +immediately clearer that this is a procedure that can be followed in order. ## Improve docs contribution processes ### Create and publish a clear process for adding and maintaining localized documentation -There is not currently a process for adding a new locale to the docs, maintaining/tracking drift in existing locales, or reviewing PRs to localized content. +There is not currently a process for adding a new locale to the docs, +maintaining/tracking drift in existing locales, or reviewing PRs to localized +content. -This has led to several locales which are minimally translated and are lacking a plan or committment from community members for ongoing maintenance. It has also led to several localization PRs and issues sitting open and unreviewed indefinitely, without contributors understanding what they need to do to get them merged. +This has led to several locales which are minimally translated and are lacking a +plan or commitment from community members for ongoing maintenance. It has also +led to several localization PRs and issues sitting open and unreviewed +indefinitely, without contributors understanding what they need to do to get +them merged. -The CNCF docs team has share the following guidance that the OpenTelemetry project uses for localizing their docs: https://opentelemetry.io/docs/contributing/localization/ +The CNCF docs team has share the following guidance that the OpenTelemetry +project uses for localizing their docs: +https://opentelemetry.io/docs/contributing/localization/ -The Helm docs maintainers should review these guidelines and make a plan for rolling out similar processes. +The Helm docs maintainers should review these guidelines and make a plan for +rolling out similar processes. ### Create and publish a clear process for triaging the issue backlog and reviewing PRs -Similar to above, the helm-www repo should have clearer processes for triaging issues and reviewing/merging PRs. As is, there are dozens of open issues and PRs that are not regularly reviewed for freshness or otherwise responded to by maintainers. Agreeing on and publishing a set of processes could make it easier for maintainers and contributors to understand how to review issues/PRs, and how long it should take for issues/PRs to be reviewed. +Similar to above, the helm-www repo should have clearer processes for triaging +issues and reviewing/merging PRs. As is, there are dozens of open issues and PRs +that are not regularly reviewed for freshness or otherwise responded to by +maintainers. Agreeing on and publishing a set of processes could make it easier +for maintainers and contributors to understand how to review issues/PRs, and how +long it should take for issues/PRs to be reviewed. -[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 \ No newline at end of file +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 From 7baf562b9d47615510814b81f48d2e54f80cabed Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 8 Dec 2025 15:19:54 -0700 Subject: [PATCH 030/104] remove unedited issues list file Signed-off-by: Paige Calvert Signed-off-by: Bruce Hamilton --- analyses/0016-helm/helm-issues-list.md | 52 -------------------------- 1 file changed, 52 deletions(-) delete mode 100644 analyses/0016-helm/helm-issues-list.md diff --git a/analyses/0016-helm/helm-issues-list.md b/analyses/0016-helm/helm-issues-list.md deleted file mode 100644 index 89c251c..0000000 --- a/analyses/0016-helm/helm-issues-list.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: _PROJECT_ Umbrella Issue and Issues List -tags: [_PROJECT_] ---- - -## Overview - -> AUTHOR NOTES: -> -> - Provide an outline or high-level description of the recommended changes. -> Note any general patterns that occur throughout the documentation, such as a -> lack of step-by-step procedures. -> -> -Items might be disjoint and unrelated; that's OK. If there are high-level -> items that must be broken down into smaller issues, use the high-level items -> to organize the issues in this plan. Otherwise, list issues in order from the -> analysis document. This is an improvement plan, not a legal brief. -> -> - The following is boilerplate language to include in the umbrella issue in -> the repo: - -This issue tracks recommended changes resulting from an analysis of the -_PROJECT_ documentation commissioned by CNCF. The analysis and supporting -documents are here: https://github.com/cncf/techdocs/tree/main/analyses under -`00NN-project`. - -The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo: -https://github.com/cncf/techdocs/issues - -## Umbrella issue - -> AUTHOR NOTE: Link to the umbrella issue in the project's documentation repo - -## Issues - -This is a list of issues representing the recommended work on the _PROJECT_ -website and technical documentation. - -> AUTHOR NOTE: Consider using the [issue](issue.md) template. - -### Issue: Item 1 - -> AUTHOR NOTE: Summarize the documentation changes prescribed by this issue. Use -> enough detail to estimate the scope of the issue. Fine-grained detail can go -> in the issue itself. In the GitHub umbrella issue, link to the sub-issue using -> a Markdown checkbox as shown below. - -- [ ] `https://github.com/_PROJECT_/repo/issues/NNN` - -### Issue: Item 2 - -> AUTHOR NOTE: ... and so on. From f2108ac3254bf7cbb5758aeb90be88ee24c18fe9 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 7 Jan 2026 13:19:52 -0700 Subject: [PATCH 031/104] run prettier on helm analysis and implementation Signed-off-by: Paige Calvert Signed-off-by: Bruce Hamilton --- analyses/0016-helm/helm-analysis.md | 218 +++++++++++----------- analyses/0016-helm/helm-implementation.md | 1 - 2 files changed, 108 insertions(+), 111 deletions(-) diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/0016-helm/helm-analysis.md index 25e8947..f37fb24 100644 --- a/analyses/0016-helm/helm-analysis.md +++ b/analyses/0016-helm/helm-analysis.md @@ -12,9 +12,9 @@ cSpell:ignore: paigecalvert subrepos kstatus Bitnami ## Introduction This document is an analysis of the effectiveness and completeness of the -[Helm][project-website] open source software (OSS) project's documentation -and website. It is funded by the CNCF Foundation as part of its overall effort -to incubate, grow, and graduate open source cloud native software projects. +[Helm][project-website] open source software (OSS) project's documentation and +website. It is funded by the CNCF Foundation as part of its overall effort to +incubate, grow, and graduate open source cloud native software projects. According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first @@ -23,26 +23,24 @@ efforts. ### Purpose -This document was written to analyze the current state of Helm -documentation. It aims to provide project leaders with an informed -understanding of potential problems in current project documentation. A second -[implementation] document outlines an actionable plan for improvement. A -third document is an [issues list] of issues to be added to the project -documentation repository. These issues can be taken up by contributors to -improve the documentation. +This document was written to analyze the current state of Helm documentation. It +aims to provide project leaders with an informed understanding of potential +problems in current project documentation. A second [implementation] document +outlines an actionable plan for improvement. A third document is an [issues +list] of issues to be added to the project documentation repository. These +issues can be taken up by contributors to improve the documentation. This document: - Analyzes the current Helm technical documentation and website - Compares existing documentation against the CNCF's standards -- Recommends a program of key improvements with the largest return on - investment +- Recommends a program of key improvements with the largest return on investment ### Scope of analysis The documentation discussed here includes the entire contents of the website, -the technical documentation, and documentation for contributors and users on -the helm-www GitHub repository. +the technical documentation, and documentation for contributors and users on the +helm-www GitHub repository. The Helm website and documentation are written in Markdown and are compiled using the Docusaurus static site generator with the theme-classic theme and @@ -62,8 +60,8 @@ GitHub repo. ### How this document is organized -This document is divided into three sections that represent three major areas -of concern: +This document is divided into three sections that represent three major areas of +concern: - **Project documentation:** concerns documentation for users of the Helm software, aimed at people who intend to use the project software @@ -77,8 +75,8 @@ Each section begins with summary ratings based on a rubric with appropriate - **Comments**: observations about the existing documentation, with a focus on how it does or does not help Helm users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness - of the documentation. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is @@ -89,8 +87,8 @@ into a series of [issues] and entered as GitHub ### How to use this document -Readers interested only in actionable improvements should skip this document -and read the **[implementation] plan** and **[issues list]**. +Readers interested only in actionable improvements should skip this document and +read the **[implementation] plan** and **[issues list]**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining @@ -100,8 +98,8 @@ to their area of concern: - [Contributor documentation](#contributor-documentation) - [Website and documentation infrastructure](#website-and-infrastructure) -Examples of CNCF documentation that demonstrate the analysis criteria are -linked from the [criteria] specification. +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria] specification. #### Recommendations, requirements, and best practices @@ -110,15 +108,15 @@ and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from -the lexicon of [RFCs][rfc-spec], the changes described here should be -understood as "recommended" or "should" at the strongest, and "optional" or -"may" in many cases. Any "must" or "required" actions are clearly denoted as -such, and pertain to legal requirements such as copyright and licensing issues. +the lexicon of [RFCs][rfc-spec], the changes described here should be understood +as "recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. ## Project documentation -Helm is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. +Helm is a **graduated** project of CNCF. This means that the project should have +[_very high_][criteria] standards for documentation. | Criterion | [Rating (1-5)] | | -------------------------- | ------------------------------ | @@ -149,9 +147,9 @@ There is some level of project overview/conceptual content on these pages: - The Introduction section (https://helm.sh/docs/intro/) includes information primarily for users of Helm charts (ie, no info for chart developers). It includes a quickstart guide that walks you through installing an example - chart, a page on how to install Helm, a page with info about common Helm - tasks like installing, upgrading, and working with repos, and a "cheat sheet" - with quick references for common CLI commands. + chart, a page on how to install Helm, a page with info about common Helm tasks + like installing, upgrading, and working with repos, and a "cheat sheet" with + quick references for common CLI commands. - There is also some high level conceptual information in the "Topics" section of the docs. For example, Helm Architecture @@ -162,8 +160,8 @@ There is some level of project overview/conceptual content on these pages: Overall, main Helm features are documented (like variables, template functions, hooks, and the Helm CLI). -But, there are several new features/breaking changes that need to be updated -for Helm 4. For example: +But, there are several new features/breaking changes that need to be updated for +Helm 4. For example: - kstatus watcher needs to be documented in the SDK docs and likely some user-facing docs needed outside of the SDK docs as well @@ -205,8 +203,8 @@ instructions. The Helm docs include some tutorials on workflows like creating different types of plugins using the different supported runtimes (eg, https://helm.sh/docs/plugins/developer/tutorial-cli-plugin). There are several -other pages that use a tutorial-style format that walks users through a -specific example in order to explain a given task or feature. For example: +other pages that use a tutorial-style format that walks users through a specific +example in order to explain a given task or feature. For example: - https://helm.sh/docs/chart_template_guide/accessing_files uses a variety of examples to explain different ways to create and access named templates @@ -224,12 +222,12 @@ are given relevant headings. There are some pages like "Using Helm" that would probably be better broken down into several smaller pages that users can see from the sidebar. Also, there are some places where there is extra info under a heading that one might not expect to find there. For example, under -[Writing a Hook](https://helm.sh/docs/topics/charts_hooks#writing-a-hook), -there is conceptual information about how hooks work, like that you can -implement multiple hooks in a single resource or that multiple resources can be +[Writing a Hook](https://helm.sh/docs/topics/charts_hooks#writing-a-hook), there +is conceptual information about how hooks work, like that you can implement +multiple hooks in a single resource or that multiple resources can be implemented as the same type of hook. These are important details about how -hooks work, but they are a bit hidden half way down a section whose heading -uses a verb phrase. +hooks work, but they are a bit hidden half way down a section whose heading uses +a verb phrase. ##### Happy path/common use cases @@ -241,18 +239,18 @@ Helm has a few different happy paths depending on the user persona: - Chart developers need to know how to work with features like values files, template functions, chart hooks, and so on -For chart users, the "happy path" of initializing a chart repository, -installing a chart, viewing release info for the chart, then uninstalling is -documented in the Quickstart workflow. The Using Helm page also touches on each -of the main tasks that a chart user would need to know about. +For chart users, the "happy path" of initializing a chart repository, installing +a chart, viewing release info for the chart, then uninstalling is documented in +the Quickstart workflow. The Using Helm page also touches on each of the main +tasks that a chart user would need to know about. As a chart developer, it's not very clear from looking at the docs sidebar if there's a most common use case or "happy path" documented. The closest page to -this is [Charts](https://helm.sh/docs/topics/charts), which does include lots -of helpful info about the chart file structure, working with chart -dependencies, templates and values, and more. However, it's a lot of info in -one page, and it doesn't necessarily walk developers through how all these -pieces should fit together to create a release. +this is [Charts](https://helm.sh/docs/topics/charts), which does include lots of +helpful info about the chart file structure, working with chart dependencies, +templates and values, and more. However, it's a lot of info in one page, and it +doesn't necessarily walk developers through how all these pieces should fit +together to create a release. ##### Clear escalation path to get more help @@ -262,13 +260,13 @@ is documented for users that need more help: - The community section of the docs (which is pulled in from the Helm community repository) includes most of the helpful info about troubleshooting. For example, https://helm.sh/community/developers/#troubleshooting provides - information about working with the community and searching the existing - issues in the Helm repo to troubleshoot. + information about working with the community and searching the existing issues + in the Helm repo to troubleshoot. -- There are also some minimal FAQs here: https://helm.sh/docs/faq/. They - include a few questions about installing and one question about uninstalling. - It looks like this information is not really an "FAQ", but rather information - about installing/uninstalling Helm that might have been documented under FAQs +- There are also some minimal FAQs here: https://helm.sh/docs/faq/. They include + a few questions about installing and one question about uninstalling. It looks + like this information is not really an "FAQ", but rather information about + installing/uninstalling Helm that might have been documented under FAQs because it lacks a more permanent home. The Helm docs lack clear troubleshooting steps for different common tasks. @@ -291,17 +289,17 @@ docs. For example: - For the Helm v4 docs, there is a fair bit of out of date content. Some of the new features haven't been fully doc'd yet -- There's also several warnings "This page has not yet been updated for Helm - 4." This content needs to be evaluated and updated +- There's also several warnings "This page has not yet been updated for Helm 4." + This content needs to be evaluated and updated #### New user content ##### Getting started content -There is Getting Started section on the site homepage. It includes Helm -download commands and a link to Artifact Hub where you can find Helm charts. It -links users to the docs for more information (specifically, it links to the -installing Helm and using Helm docs pages). +There is Getting Started section on the site homepage. It includes Helm download +commands and a link to Artifact Hub where you can find Helm charts. It links +users to the docs for more information (specifically, it links to the installing +Helm and using Helm docs pages). In terms of "getting started" docs that are clearly labeled as such, there is both an "Introduction" section and a page named "Quickstart". However, the @@ -346,9 +344,9 @@ https://github.com/helm/helm-www/blob/main/README.md#versioning: - Helm.sh releases a new version of the docs with each major release -- Helm.sh uses the version number in the URL path for non-latest versions of - the product (the latest version is served at the main /docs/ path with no - version number) +- Helm.sh uses the version number in the URL path for non-latest versions of the + product (the latest version is served at the main /docs/ path with no version + number) - Version labels on the site are updated to use the latest minor/patch version @@ -385,8 +383,8 @@ reviewing and updating the list of maintainers. #### Inclusive language -There do not appear to be any customer-facing utilities, endpoints, class -names, or feature names that use non-recommended words as documented by the +There do not appear to be any customer-facing utilities, endpoints, class names, +or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website. The docs do occasionally use language like "simple", "easy", etc. Example: @@ -398,13 +396,13 @@ https://helm.sh/docs/topics/registries/#migrating-from-chart-repos It will be helpful to find greater specificity in the naming strategy for categories. With the current naming of the sections in the sidebar, it's not -clear to docs users or contributors how the pages are grouped, and what types -of info should go where. Many sections are named by content type (how-to, -topics, FAQs, best practices). This is fine, but can be challenging to maintain -and find content when it's not clear what qualifies as each content type (for -example, Topics has become a large catch-all category). By using more specific -categories that align with a given product area or use case, it'll be more -obvious where info can be found. +clear to docs users or contributors how the pages are grouped, and what types of +info should go where. Many sections are named by content type (how-to, topics, +FAQs, best practices). This is fine, but can be challenging to maintain and find +content when it's not clear what qualifies as each content type (for example, +Topics has become a large catch-all category). By using more specific categories +that align with a given product area or use case, it'll be more obvious where +info can be found. Additionally, content throughout should be reviewed to see where there is redundant content that can be condensed. For example, lots of the pages in @@ -416,13 +414,13 @@ readability. #### New user content -The site could use a more clearly labeled "getting started" section, with -guides for all main user personas (both chart users and chart developers). For -example, a quick start that shows how to create and release a simple chart -and/or a page that explains that chart dev "happy path", including all the main -tasks a chart developer should consider as part of creating and publishing a -chart for their app. Could probably use lots of the content in Using Helm to -create getting started info for chart developers. +The site could use a more clearly labeled "getting started" section, with guides +for all main user personas (both chart users and chart developers). For example, +a quick start that shows how to create and release a simple chart and/or a page +that explains that chart dev "happy path", including all the main tasks a chart +developer should consider as part of creating and publishing a chart for their +app. Could probably use lots of the content in Using Helm to create getting +started info for chart developers. #### Content maintainability & site mechanics @@ -438,9 +436,9 @@ https://opentelemetry.io/docs/contributing/localization/. #### Content creation processes -The contributors docs could be better centralized and easier to search, maybe -in a "Contribute to the Docs" section. Currently, the contributor info is -spread across the README, +The contributors docs could be better centralized and easier to search, maybe in +a "Contribute to the Docs" section. Currently, the contributor info is spread +across the README, [CONTRIBUTING](https://github.com/paigecalvert/helm-www/blob/main/CONTRIBUTING.md), and the Community section, which makes it a bit harder to find, and harder to tell when it's out of date. @@ -460,8 +458,8 @@ help maintain inclusive, clear word choice throughout. ## Contributor documentation -Helm is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. +Helm is a **graduated** project of CNCF. This means that the project should have +[_very high_][criteria] standards for documentation. | Criterion | [Rating (1-5)] | | ----------------------------------------- | --------------------- | @@ -479,11 +477,11 @@ Contributor Documentation rubric. ##### Slack and dev meetings -The Helm Slack channels are prominently linked in the Join the Community -section on the landing page. This section also has info about upcoming events, -weekly developer stand-ups (with info on how to join), and more. Additionally, -the Community section of the website (https://helm.sh/community) also includes -this information. +The Helm Slack channels are prominently linked in the Join the Community section +on the landing page. This section also has info about upcoming events, weekly +developer stand-ups (with info on how to join), and more. Additionally, the +Community section of the website (https://helm.sh/community) also includes this +information. ##### GitHub links @@ -493,8 +491,8 @@ couple ways: - There are links on the site homepage, in the community section, and in the footer to the main Helm github -- There's an edit this page link on every docs page that allows the user to - open it in the helm-www repo in github +- There's an edit this page link on every docs page that allows the user to open + it in the helm-www repo in github ##### Mailing lists @@ -504,11 +502,11 @@ https://helm.sh/community/communication/#mailing-lists #### Beginner friendly issue backlog Docs issues are not very well triaged. There are nearly 100 open docs issues, -many irrelevant to the new site. There is also no clear triage plan or -timelines in place for addressing issues or reviewing them for freshness. +many irrelevant to the new site. There is also no clear triage plan or timelines +in place for addressing issues or reviewing them for freshness. -There is a "good first issue" label, which new contributors can use to make -code or documentation contributions. +There is a "good first issue" label, which new contributors can use to make code +or documentation contributions. In general, issues are well-documented and include helpful descriptions beyond just a title. There doesn't seem to be an issue template. @@ -529,9 +527,9 @@ first-time contributors: - https://helm.sh/community/#your-first-contribution -Also, while there's nothing specifically labeled "get help" on the site, -there's plenty of places where the slack channels, dev meetings, etc are listed -for users. +Also, while there's nothing specifically labeled "get help" on the site, there's +plenty of places where the slack channels, dev meetings, etc are listed for +users. #### Project governance documentation @@ -554,8 +552,8 @@ terms. ## Website and infrastructure -Helm is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. +Helm is a **graduated** project of CNCF. This means that the project should have +[_very high_][criteria] standards for documentation. | Criterion | [Rating (1-5)] | | ------------------------------------------- | ------------------------------ | @@ -597,8 +595,8 @@ useful for making the information more findable for users. #### Minimal website requirements Listed here are the minimal website requirements for projects based on their -[maturity level][maturity-level], either incubating or graduated. (These are -the only two levels for which a tech docs analysis can be requested.) +[maturity level][maturity-level], either incubating or graduated. (These are the +only two levels for which a tech docs analysis can be requested.) @@ -620,9 +618,9 @@ the only two levels for which a tech docs analysis can be requested.) ##### Usability / mobile experience -The website usable from mobile (doc pages are readable, and all website -features are accessible from mobile including the top-nav, site search and -in-page table of contents). +The website usable from mobile (doc pages are readable, and all website features +are accessible from mobile including the top-nav, site search and in-page table +of contents). ##### Accessibility @@ -638,10 +636,10 @@ experience for users. #### Branding and design -There is an easily recognizable brand for the project (logo + color scheme) -that is used across the website consistently. The website's typography is -consistent and easy to read. The only exception is that the font used for -headings can be somewhat difficult to read for some of the letters. +There is an easily recognizable brand for the project (logo + color scheme) that +is used across the website consistently. The website's typography is consistent +and easy to read. The only exception is that the font used for headings can be +somewhat difficult to read for some of the letters. #### Case studies/social proof diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/0016-helm/helm-implementation.md index 99cda79..802b20d 100644 --- a/analyses/0016-helm/helm-implementation.md +++ b/analyses/0016-helm/helm-implementation.md @@ -168,7 +168,6 @@ For example: - Allow signing multiple charts with single passphrase from stdin (https://github.com/helm/helm/pull/30718) - - Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) ### Review and update all the pages with the "This page has not yet been updated for Helm 4" warning From 32741da7fc791747f1f7f4ef90996035b6425dbb Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 7 Jan 2026 15:04:20 -0700 Subject: [PATCH 032/104] Add helm issues list Signed-off-by: Paige Calvert Signed-off-by: Bruce Hamilton --- analyses/0016-helm/helm-issues-list.md | 102 +++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 analyses/0016-helm/helm-issues-list.md diff --git a/analyses/0016-helm/helm-issues-list.md b/analyses/0016-helm/helm-issues-list.md new file mode 100644 index 0000000..416459e --- /dev/null +++ b/analyses/0016-helm/helm-issues-list.md @@ -0,0 +1,102 @@ +--- +title: Helm Umbrella Issue and Issues List +tags: [helm] +--- + +## Overview + +> AUTHOR NOTES: +> +> - Provide an outline or high-level description of the recommended changes. +> Note any general patterns that occur throughout the documentation, such as a +> lack of step-by-step procedures. +> +> -Items might be disjoint and unrelated; that's OK. If there are high-level +> items that must be broken down into smaller issues, use the high-level items +> to organize the issues in this plan. Otherwise, list issues in order from the +> analysis document. This is an improvement plan, not a legal brief. +> +> - The following is boilerplate language to include in the umbrella issue in +> the repo: + +## Umbrella issue + +> AUTHOR NOTE: Link to the umbrella issue in the project's documentation repo + +TO DO: Create umbrella issue in helm-www repo with the following boilerplate: + +This issue tracks recommended changes resulting from an analysis of the Helm +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `0016-helm`. + +## Issues + +This is a list of issues representing the recommended work on the Helm website +and technical documentation. + +TO DO: Create the GitHub issues in helm-www repo and add links here + +### Issue: Reorganize the sidebar + +> AUTHOR NOTE: Summarize the documentation changes prescribed by this issue. Use +> enough detail to estimate the scope of the issue. Fine-grained detail can go +> in the issue itself. In the GitHub umbrella issue, link to the sub-issue using +> a Markdown checkbox as shown below. + +Reorganize the sidebar (using the proposed sidebar in `helm-implementation.md` +as a guide) by creating new folders for each category and moving files +accordingly. Add redirects and update links as needed. Needs to be done for each +locale for v4 only. + +### Issue: Add a technical/conceptual overview of Helm + +Use existing content in +[Helm Architecture](https://helm.sh/docs/topics/architecture) to add a +high-level Helm overview page. See the proposed sidebar in +`helm-implementation.md` for instruction on where to put it. + +### Issue: Prune out-of-date content + +Review each of these pages/section to see if their content can be redistributed +or deleted: + +- "FAQs" https://helm.sh/docs/faq/installing and + https://helm.sh/docs/faq/uninstalling + +- Best practices section: https://helm.sh/docs/chart_best_practices/ + +- Tips and tricks: https://helm.sh/docs/howto/charts_tips_and_tricks + +Alternatively, if the content is still important and doesn't fit well elsewhere +in the docs, make the necessary updates so that it is up-to-date and accurate. + +### Issue: Document all the new features released with Helm 4 + +Make sure that all the Helm 4 features, improvements, and fixes are documented. +Use the full changelog for Helm 4 as a reference. + +### Issue: Review and update all the pages with the "This page has not yet been updated for Helm 4" warning + +Search the Helm v4 docs for the "This page has not yet been updated for Helm 4." +warning, which appears on several pages. Review the content on these pages and +remove or update any details that are out-of-date as of v4. + +### Issue: Rewrite tasks as step-by-step procedures + +Reformat or rewrite all tasks should to use numbered steps. For example, each of +the headings in https://helm.sh/docs/howto/chart_repository_sync_example could +be converted to a numbered step in an ordered list. + +### Issue: Create and publish a clear process for adding and maintaining localized documentation + +The CNCF docs team has share the following guidance that the OpenTelemetry +project uses for localizing their docs: +https://opentelemetry.io/docs/contributing/localization/ + +The Helm docs maintainers should review these guidelines and make a plan for +rolling out similar processes. + +### Issue: Create and publish a clear process for triaging the issue backlog and reviewing PRs + +Similar to above, agree on and publish clearer processes for triaging issues and +reviewing/merging PRs. From ca783bfb420e99c059341e4125c3a7ab34419053 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 8 Jan 2026 08:13:58 -0700 Subject: [PATCH 033/104] Fix linter and spell errors Signed-off-by: Paige Calvert Signed-off-by: Bruce Hamilton --- analyses/0016-helm/helm-implementation.md | 8 ++++---- analyses/0016-helm/helm-issues-list.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/0016-helm/helm-implementation.md index 802b20d..d599601 100644 --- a/analyses/0016-helm/helm-implementation.md +++ b/analyses/0016-helm/helm-implementation.md @@ -1,7 +1,7 @@ --- title: Implementing Helm Doc Improvements tags: [Helm] -cSpell:ignore: kstatus unreviewed +cSpell:ignore: kstatus unreviewed helmignore --- @@ -170,7 +170,7 @@ For example: (https://github.com/helm/helm/pull/30718) - Allow post-renderer to process hooks (https://github.com/helm/helm/pull/13154) -### Review and update all the pages with the "This page has not yet been updated for Helm 4" warning +### Update pages with "This page has not yet been updated for Helm 4" This warning was added to several pages in the Helm 4 docs to indicate that they've not yet been updated: @@ -212,7 +212,7 @@ immediately clearer that this is a procedure that can be followed in order. ## Improve docs contribution processes -### Create and publish a clear process for adding and maintaining localized documentation +### Create and publish a process for adding and maintaining localized docs There is not currently a process for adding a new locale to the docs, maintaining/tracking drift in existing locales, or reviewing PRs to localized @@ -231,7 +231,7 @@ https://opentelemetry.io/docs/contributing/localization/ The Helm docs maintainers should review these guidelines and make a plan for rolling out similar processes. -### Create and publish a clear process for triaging the issue backlog and reviewing PRs +### Create and publish a process for triaging issues/PRs Similar to above, the helm-www repo should have clearer processes for triaging issues and reviewing/merging PRs. As is, there are dozens of open issues and PRs diff --git a/analyses/0016-helm/helm-issues-list.md b/analyses/0016-helm/helm-issues-list.md index 416459e..e343c86 100644 --- a/analyses/0016-helm/helm-issues-list.md +++ b/analyses/0016-helm/helm-issues-list.md @@ -75,7 +75,7 @@ in the docs, make the necessary updates so that it is up-to-date and accurate. Make sure that all the Helm 4 features, improvements, and fixes are documented. Use the full changelog for Helm 4 as a reference. -### Issue: Review and update all the pages with the "This page has not yet been updated for Helm 4" warning +### Issue: Update pages with "This page has not yet been updated for Helm 4" Search the Helm v4 docs for the "This page has not yet been updated for Helm 4." warning, which appears on several pages. Review the content on these pages and @@ -87,7 +87,7 @@ Reformat or rewrite all tasks should to use numbered steps. For example, each of the headings in https://helm.sh/docs/howto/chart_repository_sync_example could be converted to a numbered step in an ordered list. -### Issue: Create and publish a clear process for adding and maintaining localized documentation +### Issue: Create and publish a process for triaging issues/PRs The CNCF docs team has share the following guidance that the OpenTelemetry project uses for localizing their docs: From 5c6748623c478bdf6cfd4d2c3a6eaf5810a9f2df Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 8 Jan 2026 10:14:39 -0700 Subject: [PATCH 034/104] shorten headings Signed-off-by: Paige Calvert Signed-off-by: Bruce Hamilton --- analyses/0016-helm/helm-issues-list.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/0016-helm/helm-issues-list.md b/analyses/0016-helm/helm-issues-list.md index e343c86..f0440c1 100644 --- a/analyses/0016-helm/helm-issues-list.md +++ b/analyses/0016-helm/helm-issues-list.md @@ -87,7 +87,7 @@ Reformat or rewrite all tasks should to use numbered steps. For example, each of the headings in https://helm.sh/docs/howto/chart_repository_sync_example could be converted to a numbered step in an ordered list. -### Issue: Create and publish a process for triaging issues/PRs +### Issue: Publish a process for adding/maintaining localized docs The CNCF docs team has share the following guidance that the OpenTelemetry project uses for localizing their docs: @@ -96,7 +96,7 @@ https://opentelemetry.io/docs/contributing/localization/ The Helm docs maintainers should review these guidelines and make a plan for rolling out similar processes. -### Issue: Create and publish a clear process for triaging the issue backlog and reviewing PRs +### Issue: Publish a process for triaging issues/PRs Similar to above, agree on and publish clearer processes for triaging issues and reviewing/merging PRs. From fd19f1b7b344470c067e4d5b9dc7629042feac82 Mon Sep 17 00:00:00 2001 From: Nate W Date: Fri, 6 Feb 2026 13:52:19 -0800 Subject: [PATCH 035/104] adding ops/servicedesk label (#336) Signed-off-by: Nate W Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- .github/settings.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/settings.yml b/.github/settings.yml index 9fbfd5d..62a1acf 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -119,6 +119,10 @@ labels: - name: wontfix description: This will not be worked on color: ffffff + - name: ops/service-desk + description: Service desk and support operations + color: 32CD32 - name: CNCF Service Desk description: This issue has a related CNCF Service Desk ticket color: 0CD9EF + From b45c51430bddb866858eb5f6982b78c3c411472c Mon Sep 17 00:00:00 2001 From: Uchechukwu Obasi Date: Sat, 21 Feb 2026 01:42:01 +0300 Subject: [PATCH 036/104] Chore: Drop numbered analysis folders and adopt a date format instead (#337) * chore: drop numbered analysis folders and adopt a date format instead Signed-off-by: thisisobate * chore: prettify docs Signed-off-by: thisisobate * chore: update check-md script Signed-off-by: thisisobate * chore: nit fix Signed-off-by: thisisobate --------- Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- .github/settings.yml | 1 - analyses/{0001-contour.md => 2021/contour/analysis.md} | 0 analyses/{0005-fluxcd.md => 2021/fluxcd/analysis.md} | 0 analyses/{0003-krator.md => 2021/krator/analysis.md} | 0 .../kubernetes-gateway-api/analysis.md} | 0 .../{0002-notary-project.md => 2021/notary/analysis.md} | 0 analyses/{0004-tremor.md => 2021/tremor/analysis.md} | 0 .../backstage}/backstage-analysis.md | 0 .../backstage}/backstage-doc-survey.csv | 0 .../backstage}/backstage-glossary.md | 0 .../backstage}/backstage-implementation.md | 0 .../backstage}/backstage-insights-summary.md | 0 .../backstage}/backstage-issues.md | 0 analyses/{0008-backstage => 2023/backstage}/index.md | 0 analyses/{0008-backstage => 2023/backstage}/user-roles.md | 0 analyses/{0010-etcd => 2023/etcd}/etcd-analysis.md | 0 analyses/{0010-etcd => 2023/etcd}/etcd-implementation.md | 0 analyses/{0010-etcd => 2023/etcd}/etcd-issues.md | 0 analyses/{0010-etcd => 2023/etcd}/index.md | 0 .../{0009-in-toto => 2023/in-toto}/in-toto-analysis.md | 0 .../{0009-in-toto => 2023/in-toto}/in-toto-doc-issues.md | 0 .../in-toto}/in-toto-implementation.md | 0 analyses/{0009-in-toto => 2023/in-toto}/index.md | 0 .../in-toto}/survey-of-existing-doc.md | 0 analyses/{0007-porter.md => 2023/porter/analysis.md} | 0 analyses/{0012-TUF => 2024/TUF}/analysis.md | 0 analyses/{0012-TUF => 2024/TUF}/implementation.md | 0 analyses/{0012-TUF => 2024/TUF}/index.md | 0 analyses/{0012-TUF => 2024/TUF}/issues.md | 0 analyses/{0011-keda => 2024/keda}/index.md | 0 analyses/{0011-keda => 2024/keda}/keda-analysis.md | 0 analyses/{0011-keda => 2024/keda}/keda-implementation.md | 0 analyses/{0011-keda => 2024/keda}/keda-issues.md | 0 .../litmuschaos}/litmuschaos-analysis.md | 0 .../litmuschaos}/litmuschaos-implementation.md | 0 .../litmuschaos}/litmuschaos-issues.md | 0 analyses/{0016-helm => 2025/helm}/helm-analysis.md | 0 analyses/{0016-helm => 2025/helm}/helm-implementation.md | 0 analyses/{0016-helm => 2025/helm}/helm-issues-list.md | 0 analyses/{0015-knative => 2025/knative}/analysis.md | 0 analyses/{0015-knative => 2025/knative}/issues.md | 0 analyses/{0014-vitess => 2025/vitess}/analysis.md | 0 analyses/index.md | 8 ++++---- package.json | 4 ++-- 44 files changed, 6 insertions(+), 7 deletions(-) rename analyses/{0001-contour.md => 2021/contour/analysis.md} (100%) rename analyses/{0005-fluxcd.md => 2021/fluxcd/analysis.md} (100%) rename analyses/{0003-krator.md => 2021/krator/analysis.md} (100%) rename analyses/{0006-gateway-api.md => 2021/kubernetes-gateway-api/analysis.md} (100%) rename analyses/{0002-notary-project.md => 2021/notary/analysis.md} (100%) rename analyses/{0004-tremor.md => 2021/tremor/analysis.md} (100%) rename analyses/{0008-backstage => 2023/backstage}/backstage-analysis.md (100%) rename analyses/{0008-backstage => 2023/backstage}/backstage-doc-survey.csv (100%) rename analyses/{0008-backstage => 2023/backstage}/backstage-glossary.md (100%) rename analyses/{0008-backstage => 2023/backstage}/backstage-implementation.md (100%) rename analyses/{0008-backstage => 2023/backstage}/backstage-insights-summary.md (100%) rename analyses/{0008-backstage => 2023/backstage}/backstage-issues.md (100%) rename analyses/{0008-backstage => 2023/backstage}/index.md (100%) rename analyses/{0008-backstage => 2023/backstage}/user-roles.md (100%) rename analyses/{0010-etcd => 2023/etcd}/etcd-analysis.md (100%) rename analyses/{0010-etcd => 2023/etcd}/etcd-implementation.md (100%) rename analyses/{0010-etcd => 2023/etcd}/etcd-issues.md (100%) rename analyses/{0010-etcd => 2023/etcd}/index.md (100%) rename analyses/{0009-in-toto => 2023/in-toto}/in-toto-analysis.md (100%) rename analyses/{0009-in-toto => 2023/in-toto}/in-toto-doc-issues.md (100%) rename analyses/{0009-in-toto => 2023/in-toto}/in-toto-implementation.md (100%) rename analyses/{0009-in-toto => 2023/in-toto}/index.md (100%) rename analyses/{0009-in-toto => 2023/in-toto}/survey-of-existing-doc.md (100%) rename analyses/{0007-porter.md => 2023/porter/analysis.md} (100%) rename analyses/{0012-TUF => 2024/TUF}/analysis.md (100%) rename analyses/{0012-TUF => 2024/TUF}/implementation.md (100%) rename analyses/{0012-TUF => 2024/TUF}/index.md (100%) rename analyses/{0012-TUF => 2024/TUF}/issues.md (100%) rename analyses/{0011-keda => 2024/keda}/index.md (100%) rename analyses/{0011-keda => 2024/keda}/keda-analysis.md (100%) rename analyses/{0011-keda => 2024/keda}/keda-implementation.md (100%) rename analyses/{0011-keda => 2024/keda}/keda-issues.md (100%) rename analyses/{0013-litmuschaos => 2024/litmuschaos}/litmuschaos-analysis.md (100%) rename analyses/{0013-litmuschaos => 2024/litmuschaos}/litmuschaos-implementation.md (100%) rename analyses/{0013-litmuschaos => 2024/litmuschaos}/litmuschaos-issues.md (100%) rename analyses/{0016-helm => 2025/helm}/helm-analysis.md (100%) rename analyses/{0016-helm => 2025/helm}/helm-implementation.md (100%) rename analyses/{0016-helm => 2025/helm}/helm-issues-list.md (100%) rename analyses/{0015-knative => 2025/knative}/analysis.md (100%) rename analyses/{0015-knative => 2025/knative}/issues.md (100%) rename analyses/{0014-vitess => 2025/vitess}/analysis.md (100%) diff --git a/.github/settings.yml b/.github/settings.yml index 62a1acf..6c575c0 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -125,4 +125,3 @@ labels: - name: CNCF Service Desk description: This issue has a related CNCF Service Desk ticket color: 0CD9EF - diff --git a/analyses/0001-contour.md b/analyses/2021/contour/analysis.md similarity index 100% rename from analyses/0001-contour.md rename to analyses/2021/contour/analysis.md diff --git a/analyses/0005-fluxcd.md b/analyses/2021/fluxcd/analysis.md similarity index 100% rename from analyses/0005-fluxcd.md rename to analyses/2021/fluxcd/analysis.md diff --git a/analyses/0003-krator.md b/analyses/2021/krator/analysis.md similarity index 100% rename from analyses/0003-krator.md rename to analyses/2021/krator/analysis.md diff --git a/analyses/0006-gateway-api.md b/analyses/2021/kubernetes-gateway-api/analysis.md similarity index 100% rename from analyses/0006-gateway-api.md rename to analyses/2021/kubernetes-gateway-api/analysis.md diff --git a/analyses/0002-notary-project.md b/analyses/2021/notary/analysis.md similarity index 100% rename from analyses/0002-notary-project.md rename to analyses/2021/notary/analysis.md diff --git a/analyses/0004-tremor.md b/analyses/2021/tremor/analysis.md similarity index 100% rename from analyses/0004-tremor.md rename to analyses/2021/tremor/analysis.md diff --git a/analyses/0008-backstage/backstage-analysis.md b/analyses/2023/backstage/backstage-analysis.md similarity index 100% rename from analyses/0008-backstage/backstage-analysis.md rename to analyses/2023/backstage/backstage-analysis.md diff --git a/analyses/0008-backstage/backstage-doc-survey.csv b/analyses/2023/backstage/backstage-doc-survey.csv similarity index 100% rename from analyses/0008-backstage/backstage-doc-survey.csv rename to analyses/2023/backstage/backstage-doc-survey.csv diff --git a/analyses/0008-backstage/backstage-glossary.md b/analyses/2023/backstage/backstage-glossary.md similarity index 100% rename from analyses/0008-backstage/backstage-glossary.md rename to analyses/2023/backstage/backstage-glossary.md diff --git a/analyses/0008-backstage/backstage-implementation.md b/analyses/2023/backstage/backstage-implementation.md similarity index 100% rename from analyses/0008-backstage/backstage-implementation.md rename to analyses/2023/backstage/backstage-implementation.md diff --git a/analyses/0008-backstage/backstage-insights-summary.md b/analyses/2023/backstage/backstage-insights-summary.md similarity index 100% rename from analyses/0008-backstage/backstage-insights-summary.md rename to analyses/2023/backstage/backstage-insights-summary.md diff --git a/analyses/0008-backstage/backstage-issues.md b/analyses/2023/backstage/backstage-issues.md similarity index 100% rename from analyses/0008-backstage/backstage-issues.md rename to analyses/2023/backstage/backstage-issues.md diff --git a/analyses/0008-backstage/index.md b/analyses/2023/backstage/index.md similarity index 100% rename from analyses/0008-backstage/index.md rename to analyses/2023/backstage/index.md diff --git a/analyses/0008-backstage/user-roles.md b/analyses/2023/backstage/user-roles.md similarity index 100% rename from analyses/0008-backstage/user-roles.md rename to analyses/2023/backstage/user-roles.md diff --git a/analyses/0010-etcd/etcd-analysis.md b/analyses/2023/etcd/etcd-analysis.md similarity index 100% rename from analyses/0010-etcd/etcd-analysis.md rename to analyses/2023/etcd/etcd-analysis.md diff --git a/analyses/0010-etcd/etcd-implementation.md b/analyses/2023/etcd/etcd-implementation.md similarity index 100% rename from analyses/0010-etcd/etcd-implementation.md rename to analyses/2023/etcd/etcd-implementation.md diff --git a/analyses/0010-etcd/etcd-issues.md b/analyses/2023/etcd/etcd-issues.md similarity index 100% rename from analyses/0010-etcd/etcd-issues.md rename to analyses/2023/etcd/etcd-issues.md diff --git a/analyses/0010-etcd/index.md b/analyses/2023/etcd/index.md similarity index 100% rename from analyses/0010-etcd/index.md rename to analyses/2023/etcd/index.md diff --git a/analyses/0009-in-toto/in-toto-analysis.md b/analyses/2023/in-toto/in-toto-analysis.md similarity index 100% rename from analyses/0009-in-toto/in-toto-analysis.md rename to analyses/2023/in-toto/in-toto-analysis.md diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/2023/in-toto/in-toto-doc-issues.md similarity index 100% rename from analyses/0009-in-toto/in-toto-doc-issues.md rename to analyses/2023/in-toto/in-toto-doc-issues.md diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/2023/in-toto/in-toto-implementation.md similarity index 100% rename from analyses/0009-in-toto/in-toto-implementation.md rename to analyses/2023/in-toto/in-toto-implementation.md diff --git a/analyses/0009-in-toto/index.md b/analyses/2023/in-toto/index.md similarity index 100% rename from analyses/0009-in-toto/index.md rename to analyses/2023/in-toto/index.md diff --git a/analyses/0009-in-toto/survey-of-existing-doc.md b/analyses/2023/in-toto/survey-of-existing-doc.md similarity index 100% rename from analyses/0009-in-toto/survey-of-existing-doc.md rename to analyses/2023/in-toto/survey-of-existing-doc.md diff --git a/analyses/0007-porter.md b/analyses/2023/porter/analysis.md similarity index 100% rename from analyses/0007-porter.md rename to analyses/2023/porter/analysis.md diff --git a/analyses/0012-TUF/analysis.md b/analyses/2024/TUF/analysis.md similarity index 100% rename from analyses/0012-TUF/analysis.md rename to analyses/2024/TUF/analysis.md diff --git a/analyses/0012-TUF/implementation.md b/analyses/2024/TUF/implementation.md similarity index 100% rename from analyses/0012-TUF/implementation.md rename to analyses/2024/TUF/implementation.md diff --git a/analyses/0012-TUF/index.md b/analyses/2024/TUF/index.md similarity index 100% rename from analyses/0012-TUF/index.md rename to analyses/2024/TUF/index.md diff --git a/analyses/0012-TUF/issues.md b/analyses/2024/TUF/issues.md similarity index 100% rename from analyses/0012-TUF/issues.md rename to analyses/2024/TUF/issues.md diff --git a/analyses/0011-keda/index.md b/analyses/2024/keda/index.md similarity index 100% rename from analyses/0011-keda/index.md rename to analyses/2024/keda/index.md diff --git a/analyses/0011-keda/keda-analysis.md b/analyses/2024/keda/keda-analysis.md similarity index 100% rename from analyses/0011-keda/keda-analysis.md rename to analyses/2024/keda/keda-analysis.md diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/2024/keda/keda-implementation.md similarity index 100% rename from analyses/0011-keda/keda-implementation.md rename to analyses/2024/keda/keda-implementation.md diff --git a/analyses/0011-keda/keda-issues.md b/analyses/2024/keda/keda-issues.md similarity index 100% rename from analyses/0011-keda/keda-issues.md rename to analyses/2024/keda/keda-issues.md diff --git a/analyses/0013-litmuschaos/litmuschaos-analysis.md b/analyses/2024/litmuschaos/litmuschaos-analysis.md similarity index 100% rename from analyses/0013-litmuschaos/litmuschaos-analysis.md rename to analyses/2024/litmuschaos/litmuschaos-analysis.md diff --git a/analyses/0013-litmuschaos/litmuschaos-implementation.md b/analyses/2024/litmuschaos/litmuschaos-implementation.md similarity index 100% rename from analyses/0013-litmuschaos/litmuschaos-implementation.md rename to analyses/2024/litmuschaos/litmuschaos-implementation.md diff --git a/analyses/0013-litmuschaos/litmuschaos-issues.md b/analyses/2024/litmuschaos/litmuschaos-issues.md similarity index 100% rename from analyses/0013-litmuschaos/litmuschaos-issues.md rename to analyses/2024/litmuschaos/litmuschaos-issues.md diff --git a/analyses/0016-helm/helm-analysis.md b/analyses/2025/helm/helm-analysis.md similarity index 100% rename from analyses/0016-helm/helm-analysis.md rename to analyses/2025/helm/helm-analysis.md diff --git a/analyses/0016-helm/helm-implementation.md b/analyses/2025/helm/helm-implementation.md similarity index 100% rename from analyses/0016-helm/helm-implementation.md rename to analyses/2025/helm/helm-implementation.md diff --git a/analyses/0016-helm/helm-issues-list.md b/analyses/2025/helm/helm-issues-list.md similarity index 100% rename from analyses/0016-helm/helm-issues-list.md rename to analyses/2025/helm/helm-issues-list.md diff --git a/analyses/0015-knative/analysis.md b/analyses/2025/knative/analysis.md similarity index 100% rename from analyses/0015-knative/analysis.md rename to analyses/2025/knative/analysis.md diff --git a/analyses/0015-knative/issues.md b/analyses/2025/knative/issues.md similarity index 100% rename from analyses/0015-knative/issues.md rename to analyses/2025/knative/issues.md diff --git a/analyses/0014-vitess/analysis.md b/analyses/2025/vitess/analysis.md similarity index 100% rename from analyses/0014-vitess/analysis.md rename to analyses/2025/vitess/analysis.md diff --git a/analyses/index.md b/analyses/index.md index e4c9eae..8f3ba9e 100644 --- a/analyses/index.md +++ b/analyses/index.md @@ -50,11 +50,11 @@ This directory contains completed analyses of the technical documentation for selected CNCF incubating and graduated software projects. The analyses are in one of two formats depending on when they were written. -Earlier analyses (**0001** - **0007**) are Markdown files, each of which is the -sole artifact of the analysis. +Earlier analyses (**2021**) have one project directory per project, and each of +those directories contains a single Markdown file as the only analysis artifact. -Subsequent analyses (**0008-** forward) each have their own directory containing -three analysis artifacts: +Subsequent analyses (**2023** onward) also use one directory per project, with +each directory containing one or more of these three artifact types: - [analysis.md](../docs/analysis/templates/analysis.md) evaluates the project documentation and provides comments and recommendations in a manner very diff --git a/package.json b/package.json index d41d791..a9bd975 100644 --- a/package.json +++ b/package.json @@ -14,8 +14,8 @@ "_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'", - "_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path '*/00*'", - "_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010'", + "_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path './analyses/*'", + "_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path './analyses/*'", "_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'", "_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'", "build:preview": "npm run _build", From 86123c7f49fc7c147361869424a487a9c6ffc800 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Thu, 26 Feb 2026 21:37:41 -0800 Subject: [PATCH 037/104] Update analysis.md Added template and started customizing Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/analysis/templates/analysis.md | 72 +++++++++++------------------ 1 file changed, 26 insertions(+), 46 deletions(-) diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index e6103fa..24c9bf0 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -1,37 +1,17 @@ --- -title: _PROJECT_ Documentation Analysis -tags: [_PROJECT_] -created: YYYY-MM-DD -modified: YYYY-MM-DD -author: _NAME_ (@_HANDLE_) +title: Flatcar Documentation Analysis +tags: [Flatcar] +created: 2026-02-26 +modified: 2026-02-26 +author: Bruce Hamilton (@iRaindrop) --- -## About this template - -TO USE THIS TEMPLATE, search and replace the named IDs: - -- `_PROJECT_`: project name -- `YYYY-MM-DD`: creation and modification dates of the analysis document -- `_NAME_`: name of the analysis author -- `@_HANDLE_`: GitHub handle of the analysis author -- `_PROJECT-WEBSITE_`: landing page of the project's information website -- `_PROJECT-DOC-URL_`: main page of the technical documentation for the current - project revision; this might be on the main website server, for example as - _PROJECT-WEBSITE_/doc -- `_PROJECT-DOC-REPO_`: repository where the project technical documentation is - stored; this might be its own repo or a directory in the project main repo - -For the analysis procedure, see [Analysis how-to](../howto.md). - -> Note: delete this "About this template" section after you have customized this -> template for a specific project. - ## Introduction This document is an analyzes the effectiveness and completeness of the -[_PROJECT_][project-website] open source software (OSS) project's documentation +[Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. @@ -42,7 +22,7 @@ efforts. ### Purpose -This document was written to analyze the current state of _PROJECT_ +This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, , outlines an actionable plan for improvement. A @@ -52,7 +32,7 @@ improve the documentation. This document: -- Analyzes the current _PROJECT_ technical documentation and website +- Analyzes the current Flatcar technical documentation and website - Compares existing documentation against the CNCF’s standards - Recommends a program of key improvements with the largest return on investment @@ -60,24 +40,24 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the -_PROJECT_ GitHub repository. +Flatcar GitHub repository. -The _PROJECT_ website and documentation are written in [Markdown, ReStructured +The Flatcar website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify -platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. +platform, other]. The site's code is stored on the Flatcar GitHub repo. #### In scope -- Website: _PROJECT-WEBSITE_ -- Documentation: _PROJECT-DOC-URL_ -- Website repo: _PROJECT-DOC-REPO_ +- Website: https://www.flatcar.org/ +- Documentation: https://www.flatcar.org/docs/latest +- Website repo: https://github.com/cncf/techdocs - _[Other; might include a demo server, governance site, or other relevant repositories]_ #### Out of scope -- Other _PROJECT_ repos: _[In general, do not include sub-projects or related +- Other Flatcar repos: _[In general, do not include sub-projects or related "ecosystem" projects]_ ### How this document is organized @@ -85,10 +65,10 @@ platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. This document is divided into three sections that represent three major areas of concern: -- **Project documentation:** concerns documentation for users of the _PROJECT_ +- **Project documentation:** concerns documentation for users of the Flatcar software, aimed at people who intend to use the project software - **Contributor documentation:** concerns documentation for new and existing - contributors to the _PROJECT_ OSS project + contributors to the Flatcar OSS project - **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability @@ -96,7 +76,7 @@ Each section begins with summary ratings based on a rubric with appropriate [criteria] for the section, then proceeds to: - **Comments**: observations about the existing documentation, with a focus on - how it does or does not help _PROJECT_ users achieve their goals. + how it does or does not help Flatcar users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. @@ -138,12 +118,12 @@ to legal requirements such as copyright and licensing issues. > AUTHOR NOTE: Pick the CNCF maturity level of the project: -_PROJECT_ is a **graduated** project of CNCF. This means that the project should +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -_PROJECT_ is an **incubating** project of CNCF. This means that the project +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -254,12 +234,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -_PROJECT_ is a **graduated** project of CNCF. This means that the project should +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -_PROJECT_ is an **incubating** project of CNCF. This means that the project +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -344,12 +324,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -_PROJECT_ is a **graduated** project of CNCF. This means that the project should +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -_PROJECT_ is an **incubating** project of CNCF. This means that the project +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -550,8 +530,8 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-doc-website]: ./?_PROJECT-DOC-URL_ -[project-website]: ./?_PROJECT-WEBSITE_ +[project-doc-website]: ./?https://www.flatcar.org/docs/latest +[project-website]: ./?https://www.flatcar.org/ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md From fe748eaa5abd8af342dc8267bd104d97eee4827c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Fri, 27 Feb 2026 20:43:20 -0800 Subject: [PATCH 038/104] File fix - added analysis.md Also restored mistakenly used template Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 537 ++++++++++++++++++++++++++++ docs/analysis/templates/analysis.md | 72 ++-- 2 files changed, 583 insertions(+), 26 deletions(-) create mode 100644 analyses/2026/flatcar/analysis.md diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md new file mode 100644 index 0000000..24c9bf0 --- /dev/null +++ b/analyses/2026/flatcar/analysis.md @@ -0,0 +1,537 @@ +--- +title: Flatcar Documentation Analysis +tags: [Flatcar] +created: 2026-02-26 +modified: 2026-02-26 +author: Bruce Hamilton (@iRaindrop) +--- + + + +## Introduction + +This document is an analyzes the effectiveness and completeness of the +[Flatcar][project-website] open source software (OSS) project's documentation +and website. It is funded by the CNCF Foundation as part of its overall effort +to incubate, grow, and graduate open source cloud native software projects. + +According to CNCF best practices guidelines, effective documentation is a +prerequisite for program graduation. The documentation analysis is the first +step of a CNCF process aimed at assisting projects with their documentation +efforts. + +### Purpose + +This document was written to analyze the current state of Flatcar +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second +[implementation] document, , outlines an actionable plan for improvement. A +third document is an [issues list] of issues to be added to the project +documentation repository. These issues can be taken up by contributors to +improve the documentation. + +This document: + +- Analyzes the current Flatcar technical documentation and website +- Compares existing documentation against the CNCF’s standards +- Recommends a program of key improvements with the largest return on investment + +### Scope of analysis + +The documentation discussed here includes the entire contents of the website, +the technical documentation, and documentation for contributors and users on the +Flatcar GitHub repository. + +The Flatcar website and documentation are written in [Markdown, ReStructured +Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static +site generator with the [Docsy, other] theme and served from [the Netlify +platform, other]. The site's code is stored on the Flatcar GitHub repo. + +#### In scope + +- Website: https://www.flatcar.org/ +- Documentation: https://www.flatcar.org/docs/latest +- Website repo: https://github.com/cncf/techdocs +- _[Other; might include a demo server, governance site, or other relevant + repositories]_ + +#### Out of scope + +- Other Flatcar repos: _[In general, do not include sub-projects or related + "ecosystem" projects]_ + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** concerns documentation for users of the Flatcar + software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Flatcar OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability + +Each section begins with summary ratings based on a rubric with appropriate +[criteria] for the section, then proceeds to: + +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help Flatcar users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [implementation] document breaks the recommendations down into +concrete actions that can be implemented by project contributors. Its focus is +on drilling down to specific, achievable work that can be completed in +constrained blocks of time. Ultimately, the implementation items are decomposed +into a series of [issues] and entered as GitHub [project-doc-website]/issues. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the **[implementation] plan** and **[issues] list**. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation](./?TODO=ADD-URL) +- [Contributor documentation](./?TODO=ADD-URL) +- [Website and documentation infrastructure](./?TODO=ADD-URL) + +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria] specification. + +#### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards, +and suggests possible improvements. In most cases there is more than one way to +do things. Few recommendations here are meant to be prescriptive. Rather, the +recommended implementations represent the reviewers' experience with how to +apply documentation best practices. In other words, borrowing terminology from +the lexicon of [RFCs][rfc-spec], the changes described here should be understood +as "recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. + +## Project documentation + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Flatcar is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Flatcar is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria] professional-quality documentation alongside +the project code. + +| Criterion | [Rating (1-5)] | +| -------------------------- | -------------- | +| Information architecture | [rating (1-5)] | +| New user content | [rating (1-5)] | +| Content maintainability | [rating (1-5)] | +| Content creation processes | [rating (1-5)] | +| Inclusive language | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Project Documentation here. + +The following sections contain brief assessments of each element of the Project +Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and +> especially the technical documentation, meet these criteria. (Criteria are +> copied from criteria.md) + +#### Information architecture + +The overall structure (pages/subpages/sections/subsections) of your project +documentation. We evaluate on the following: + +- Is there high level conceptual/“About” content? Is the documentation feature + complete? (i.e., each product feature is documented) +- Are there step-by-step instructions (tasks, tutorials) documented for + features? +- Are there any key features which are documented but missing task + documentation? +- Is the “happy path”/most common use case documented? Does task and tutorial + content demonstrate atomicity and isolation of concerns? (Are tasks clearly + named according to user goals?) +- If the documentation does not suffice, is there a clear escalation path for + users needing more help? (FAQ, Troubleshooting) +- If the product exposes an API, is there a complete reference? +- Is content up to date and accurate? + +#### New user content + +New users are the most avid users of documentation, and need content +specifically for them. We evaluate on the following: + +- Is “getting started” clearly labeled? (“Getting started”, “Installation”, + “First steps”, etc.) +- Is installation documented step-by-step? +- If needed, are multiple OSes documented? +- Do users know where to go after reading the getting started guide? +- Is your new user content clearly signposted on your site’s homepage or at the + top of your information architecture? +- Is there sample code or other example content that can easily be copy-pasted? + +#### Content maintainability & site mechanics + +As a project scales, concerns like localized (translated) content and versioning +become large maintenance burdens, particularly if you don’t plan for them. + +We evaluate on the following: + +- Is your documentation searchable? +- Are you planning for localization/internationalization with regards to site + directory structure? Is a localization framework present? +- Do you have a clearly documented method for versioning your content? + +#### Content creation processes + +Documentation is only as useful as it is accurate and well-maintained, and +requires the same kind of review and approval processes as code. + +We evaluate on the following: + +- Is there a clearly documented (ongoing) contribution process for + documentation? +- Does your code release process account for documentation creation & updates? +- Who reviews and approves documentation pull requests? +- Does the website have a clear owner/maintainer? + +#### Inclusive language + +Creating inclusive project communities is a key goal for all CNCF projects. + +We evaluate on the following: + +- Are there any customer-facing utilities, endpoints, class names, or feature + names that use non-recommended words as documented by the + [Inclusive Naming Initiative](https://inclusivenaming.org) website? +- Does the project use language like "simple", "easy", etc.? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Information architecture + +#### New user content + +#### Content maintainability & site mechanics + +#### Content creation processes + +#### Inclusive language + +## Contributor documentation + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Flatcar is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Flatcar is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria] professional-quality documentation alongside +the project code. + +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | [rating (1-5)] | +| Beginner friendly issue backlog | [rating (1-5)] | +| “New contributor” getting started content | [rating (1-5)] | +| Project governance documentation | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Contributor Documentation +> here. + +The following sections contain brief assessments of each element of the +Contributor Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the contributor documentation might +> be contained in the documentation repository. (Criteria are copied from +> criteria.md) + +#### Communication methods documented + +One of the easiest ways to attract new contributors is making sure they know how +to reach you. + +We evaluate on the following: + +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked + from your website? +- Is there a direct link to your GitHub organization/repository? +- Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings? +- Are mailing lists documented? + +#### Beginner friendly issue backlog + +We evaluate on the following: + +- Are docs issues well-triaged? +- Is there a clearly marked way for new contributors to make code or + documentation contributions (i.e. a “good first issue” label)? +- Are issues well-documented (i.e., more than just a title)? +- Are issues maintained for staleness? + +#### New contributor getting started content + +Open source is complex and projects have many processes to manage that. Are +processes easy to understand and written down so that new contributors can jump +in easily? + +We evaluate on the following: + +- Do you have a community repository or section on your website? +- Is there a document specifically for new contributors/your first contribution? +- Do new users know where to get help? + +#### Project governance documentation + +One of the CNCF’s core project values is open governance. + +We evaluate on the following: + +- Is project governance clearly documented? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Communication methods documented + +#### Beginner friendly issue backlog + +#### New contributor getting started content + +#### Project governance documentation + +## Website and infrastructure + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Flatcar is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Flatcar is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria] professional-quality documentation alongside +the project code. + +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | [rating (1-5)] | +| Meets min website req. (for maturity level) | [rating (1-5)] | +| Usability, accessibility, and design | [rating (1-5)] | +| Branding and design | [rating (1-5)] | +| Case studies/social proof | [rating (1-5)] | +| SEO, Analytics, and site-local search | [rating (1-5)] | +| Maintenance planning | [rating (1-5)] | +| A11y plan & implementation | [rating (1-5)] | +| Mobile-first plan & impl. | [rating (1-5)] | +| HTTPS access & HTTP redirect | [rating (1-5)] | +| Google Analytics 4 for production only | [rating (1-5)] | +| Indexing allowed for production server only | [rating (1-5)] | +| Intra-site / local search | [rating (1-5)] | +| Account custodians are documented | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Website and documentation +> infrastructure here. + +The following sections contain brief assessments of each element of the Website +and documentation infrastructure rubric. + +> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the website infrastructure criteria +> depend on the tools (static site generator, website framework and hosting, +> analytics tools, etc.) and processes (project CI, release procedures, +> governance, etc.) used to produce the documentation. (Criteria are copied from +> criteria.md) + +#### Single-source requirement + +Source files for _all website pages_ should reside in a single repo. Among other +problems, keeping source files in two places: + +- confuses contributors +- requires you to keep two sources in sync +- increases the likelihood of errors +- 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][git-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. + +#### Minimal website requirements + +Listed here are the minimal website requirements for projects based on their +[maturity level][maturity-level], either incubating or graduated. (These are the +only two levels for which a tech docs analysis can be requested.) + + + +| Criterion | Incubating Requirement | Graduated Requirement | +| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | +| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + + + +[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[maturity-level]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[cncf-servicedesk]: https://servicedesk.cncf.io + +#### Usability, accessibility and devices + +Most CNCF websites are accessed from mobile and other non-desktop devices at +least 10-20% of the time. Planning for this early in your website's design will +be much less effort than retrofitting a desktop-first design. + +- Is the website usable from mobile? +- Are doc pages readable? +- Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? +- Might a [mobile-first] design make sense for your project? + +[mobile-first]: + https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first + +Plan for suitable [accessibility][] measures for your website. For example: + +- Are color contrasts significant enough for color-impaired readers? +- Are most website features usable using a keyboard only? +- Does text-to-speech offer listeners a good experience? + +It is up to each project to set their own guidelines. + +[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility + +#### Branding and design + +CNCF seeks to support enterprise-ready open source software. A key aspect of +this is branding and marketing. + +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? + +#### Case studies/social proof + +One of the best ways to advertise an open source project is to show other +organizations using it. + +We evaluate on the following: + +- Are there case studies available for the project and are they documented on + the website? +- Are there user testimonials available? +- Is there an active project blog? +- Are there community talks for the project and are they present on the website? +- Is there a logo wall of users/participating organizations? + +#### 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. + +We evaluate on the following: + +- Analytics: + - Is analytics enabled for the production server? + - Is analytics disabled for all other deploys? + - If your project used Google Analytics, have you migrated to GA4? + - Can Page-not-found (404) reports easily be generated from you site + analytics? Provide a sample of the site's current top-10 404s. +- Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches? +- Is local intra-site search available from the website? +- Are the current custodian(s) of the following accounts clearly documented: + analytics, Google Search Console, site-search (such as Google CSE or Algolia) + +#### Maintenance planning + +Website maintenance is an important part of project success, especially when +project maintainers aren’t web developers. + +We evaluate on the following: + +- Is your website tooling well supported by the community (i.e., Hugo with the + Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) +- Are you actively cultivating website maintainers from within the community? +- Are site build times reasonable? +- Do site maintainers have adequate permissions? + +#### Other + +- Is your website accessible via HTTPS? +- Does HTTP access, if any, redirect to HTTPS? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Single-source requirement + +#### Minimal website requirements + +#### Usability, accessibility and devices + +#### Branding and design + +#### Case studies/social proof + +#### SEO, Analytics and site-local search + +#### Maintenance planning + +#### Other + +#### References and notes + +##### Rating values + +The numeric rating values used in this document are as follows + +1. Not present +2. Needs improvement +3. Meets standards +4. Meets or exceeds standards +5. Exemplary + +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues-list.md +[project-doc-website]: ./?https://www.flatcar.org/docs/latest +[project-website]: ./?https://www.flatcar.org/ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index 24c9bf0..e6103fa 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -1,17 +1,37 @@ --- -title: Flatcar Documentation Analysis -tags: [Flatcar] -created: 2026-02-26 -modified: 2026-02-26 -author: Bruce Hamilton (@iRaindrop) +title: _PROJECT_ Documentation Analysis +tags: [_PROJECT_] +created: YYYY-MM-DD +modified: YYYY-MM-DD +author: _NAME_ (@_HANDLE_) --- +## About this template + +TO USE THIS TEMPLATE, search and replace the named IDs: + +- `_PROJECT_`: project name +- `YYYY-MM-DD`: creation and modification dates of the analysis document +- `_NAME_`: name of the analysis author +- `@_HANDLE_`: GitHub handle of the analysis author +- `_PROJECT-WEBSITE_`: landing page of the project's information website +- `_PROJECT-DOC-URL_`: main page of the technical documentation for the current + project revision; this might be on the main website server, for example as + _PROJECT-WEBSITE_/doc +- `_PROJECT-DOC-REPO_`: repository where the project technical documentation is + stored; this might be its own repo or a directory in the project main repo + +For the analysis procedure, see [Analysis how-to](../howto.md). + +> Note: delete this "About this template" section after you have customized this +> template for a specific project. + ## Introduction This document is an analyzes the effectiveness and completeness of the -[Flatcar][project-website] open source software (OSS) project's documentation +[_PROJECT_][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. @@ -22,7 +42,7 @@ efforts. ### Purpose -This document was written to analyze the current state of Flatcar +This document was written to analyze the current state of _PROJECT_ documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, , outlines an actionable plan for improvement. A @@ -32,7 +52,7 @@ improve the documentation. This document: -- Analyzes the current Flatcar technical documentation and website +- Analyzes the current _PROJECT_ technical documentation and website - Compares existing documentation against the CNCF’s standards - Recommends a program of key improvements with the largest return on investment @@ -40,24 +60,24 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the -Flatcar GitHub repository. +_PROJECT_ GitHub repository. -The Flatcar website and documentation are written in [Markdown, ReStructured +The _PROJECT_ website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify -platform, other]. The site's code is stored on the Flatcar GitHub repo. +platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. #### In scope -- Website: https://www.flatcar.org/ -- Documentation: https://www.flatcar.org/docs/latest -- Website repo: https://github.com/cncf/techdocs +- Website: _PROJECT-WEBSITE_ +- Documentation: _PROJECT-DOC-URL_ +- Website repo: _PROJECT-DOC-REPO_ - _[Other; might include a demo server, governance site, or other relevant repositories]_ #### Out of scope -- Other Flatcar repos: _[In general, do not include sub-projects or related +- Other _PROJECT_ repos: _[In general, do not include sub-projects or related "ecosystem" projects]_ ### How this document is organized @@ -65,10 +85,10 @@ platform, other]. The site's code is stored on the Flatcar GitHub repo. This document is divided into three sections that represent three major areas of concern: -- **Project documentation:** concerns documentation for users of the Flatcar +- **Project documentation:** concerns documentation for users of the _PROJECT_ software, aimed at people who intend to use the project software - **Contributor documentation:** concerns documentation for new and existing - contributors to the Flatcar OSS project + contributors to the _PROJECT_ OSS project - **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability @@ -76,7 +96,7 @@ Each section begins with summary ratings based on a rubric with appropriate [criteria] for the section, then proceeds to: - **Comments**: observations about the existing documentation, with a focus on - how it does or does not help Flatcar users achieve their goals. + how it does or does not help _PROJECT_ users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. @@ -118,12 +138,12 @@ to legal requirements such as copyright and licensing issues. > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -234,12 +254,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -324,12 +344,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -530,8 +550,8 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-doc-website]: ./?https://www.flatcar.org/docs/latest -[project-website]: ./?https://www.flatcar.org/ +[project-doc-website]: ./?_PROJECT-DOC-URL_ +[project-website]: ./?_PROJECT-WEBSITE_ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md From 7bf87ef4e197b9a9f07b95efd0ee23971eb998a6 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Fri, 27 Feb 2026 21:49:39 -0800 Subject: [PATCH 039/104] Update analysis.md Formatting fixes Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 240 ++++++++---------------------- 1 file changed, 65 insertions(+), 175 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 24c9bf0..8a320cf 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,25 +10,13 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analyzes the effectiveness and completeness of the -[Flatcar][project-website] open source software (OSS) project's documentation -and website. It is funded by the CNCF Foundation as part of its overall effort -to incubate, grow, and graduate open source cloud native software projects. +This document is an analyzes the effectiveness and completeness of the [Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. -According to CNCF best practices guidelines, effective documentation is a -prerequisite for program graduation. The documentation analysis is the first -step of a CNCF process aimed at assisting projects with their documentation -efforts. +According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. ### Purpose -This document was written to analyze the current state of Flatcar -documentation. It aims to provide project leaders with an informed understanding -of potential problems in current project documentation. A second -[implementation] document, , outlines an actionable plan for improvement. A -third document is an [issues list] of issues to be added to the project -documentation repository. These issues can be taken up by contributors to -improve the documentation. +This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, , outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. This document: @@ -38,94 +26,57 @@ This document: ### Scope of analysis -The documentation discussed here includes the entire contents of the website, -the technical documentation, and documentation for contributors and users on the -Flatcar GitHub repository. +The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the Flatcar GitHub repository. -The Flatcar website and documentation are written in [Markdown, ReStructured -Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static -site generator with the [Docsy, other] theme and served from [the Netlify -platform, other]. The site's code is stored on the Flatcar GitHub repo. +The Flatcar website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the Flatcar GitHub repo. #### In scope - Website: https://www.flatcar.org/ - Documentation: https://www.flatcar.org/docs/latest - Website repo: https://github.com/cncf/techdocs -- _[Other; might include a demo server, governance site, or other relevant - repositories]_ #### Out of scope -- Other Flatcar repos: _[In general, do not include sub-projects or related - "ecosystem" projects]_ ### How this document is organized -This document is divided into three sections that represent three major areas of -concern: +This document is divided into three sections that represent three major areas of concern: -- **Project documentation:** concerns documentation for users of the Flatcar - software, aimed at people who intend to use the project software -- **Contributor documentation:** concerns documentation for new and existing - contributors to the Flatcar OSS project -- **Website:** concerns the mechanics of publishing the documentation, and - includes branding, website structure, and maintainability +- **Project documentation:** concerns documentation for users of the Flatcar software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing contributors to the Flatcar OSS project +- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability -Each section begins with summary ratings based on a rubric with appropriate -[criteria] for the section, then proceeds to: +Each section begins with summary ratings based on a rubric with appropriate [criteria] for the section, then proceeds to: -- **Comments**: observations about the existing documentation, with a focus on - how it does or does not help Flatcar users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness of - the documentation. +- **Comments**: observations about the existing documentation, with a focus on how it does or does not help Flatcar users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of the documentation. -The accompanying [implementation] document breaks the recommendations down into -concrete actions that can be implemented by project contributors. Its focus is -on drilling down to specific, achievable work that can be completed in -constrained blocks of time. Ultimately, the implementation items are decomposed -into a series of [issues] and entered as GitHub [project-doc-website]/issues. +The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of [issues] and entered as GitHub [project-doc-website]/issues. ### How to use this document -Readers interested only in actionable improvements should skip this document and -read the **[implementation] plan** and **[issues] list**. +Readers interested only in actionable improvements should skip this document and read the **[implementation] plan** and **[issues] list**. -Readers interested in the current state of the documentation and the reasoning -behind the recommendations should read the section of this document pertaining -to their area of concern: +Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: - [Project documentation](./?TODO=ADD-URL) - [Contributor documentation](./?TODO=ADD-URL) - [Website and documentation infrastructure](./?TODO=ADD-URL) -Examples of CNCF documentation that demonstrate the analysis criteria are linked -from the [criteria] specification. +Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. #### Recommendations, requirements, and best practices -This analysis measures documentation against CNCF project maturity standards, -and suggests possible improvements. In most cases there is more than one way to -do things. Few recommendations here are meant to be prescriptive. Rather, the -recommended implementations represent the reviewers' experience with how to -apply documentation best practices. In other words, borrowing terminology from -the lexicon of [RFCs][rfc-spec], the changes described here should be understood -as "recommended" or "should" at the strongest, and "optional" or "may" in many -cases. Any "must" or "required" actions are clearly denoted as such, and pertain -to legal requirements such as copyright and licensing issues. +This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-spec], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. ## Project documentation > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -Flatcar is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside -the project code. +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. + > AUTHOR NOTE: or + Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | -------------------------- | -------------- | @@ -142,64 +93,47 @@ the project code. The following sections contain brief assessments of each element of the Project Documentation rubric. -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and -> especially the technical documentation, meet these criteria. (Criteria are -> copied from criteria.md) +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and > especially the technical documentation, meet these criteria. (Criteria are > copied from criteria.md) #### Information architecture -The overall structure (pages/subpages/sections/subsections) of your project -documentation. We evaluate on the following: - -- Is there high level conceptual/“About” content? Is the documentation feature - complete? (i.e., each product feature is documented) -- Are there step-by-step instructions (tasks, tutorials) documented for - features? -- Are there any key features which are documented but missing task - documentation? -- Is the “happy path”/most common use case documented? Does task and tutorial - content demonstrate atomicity and isolation of concerns? (Are tasks clearly - named according to user goals?) -- If the documentation does not suffice, is there a clear escalation path for - users needing more help? (FAQ, Troubleshooting) +The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: + +- Is there high level conceptual/“About” content? Is the documentation feature complete? (i.e., each product feature is documented) - Are there step-by-step instructions (tasks, tutorials) documented for features? +- Are there any key features which are documented but missing task documentation? +- Is the “happy path”/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) +- If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) - If the product exposes an API, is there a complete reference? - Is content up to date and accurate? #### New user content -New users are the most avid users of documentation, and need content -specifically for them. We evaluate on the following: +New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: -- Is “getting started” clearly labeled? (“Getting started”, “Installation”, - “First steps”, etc.) +- Is “getting started” clearly labeled? (“Getting started”, “Installation”, “First steps”, etc.) - Is installation documented step-by-step? - If needed, are multiple OSes documented? - Do users know where to go after reading the getting started guide? -- Is your new user content clearly signposted on your site’s homepage or at the - top of your information architecture? +- Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? - Is there sample code or other example content that can easily be copy-pasted? #### Content maintainability & site mechanics -As a project scales, concerns like localized (translated) content and versioning -become large maintenance burdens, particularly if you don’t plan for them. +As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. We evaluate on the following: - Is your documentation searchable? -- Are you planning for localization/internationalization with regards to site - directory structure? Is a localization framework present? +- Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? - Do you have a clearly documented method for versioning your content? #### Content creation processes -Documentation is only as useful as it is accurate and well-maintained, and -requires the same kind of review and approval processes as code. +Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. We evaluate on the following: -- Is there a clearly documented (ongoing) contribution process for - documentation? +- Is there a clearly documented (ongoing) contribution process for documentation? - Does your code release process account for documentation creation & updates? - Who reviews and approves documentation pull requests? - Does the website have a clear owner/maintainer? @@ -210,15 +144,13 @@ Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: -- Are there any customer-facing utilities, endpoints, class names, or feature - names that use non-recommended words as documented by the +- Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website? - Does the project use language like "simple", "easy", etc.? ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. +> AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. #### Information architecture @@ -234,14 +166,11 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside -the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | @@ -252,29 +181,21 @@ the project code. ### Comments -> AUTHOR NOTE: make any overall comments about the Contributor Documentation -> here. +> AUTHOR NOTE: make any overall comments about the Contributor Documentation > here. -The following sections contain brief assessments of each element of the -Contributor Documentation rubric. +The following sections contain brief assessments of each element of the Contributor Documentation rubric. -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the contributor documentation might -> be contained in the documentation repository. (Criteria are copied from -> criteria.md) +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet > these criteria. Keep in mind that much of the contributor documentation might > be contained in the documentation repository. (Criteria are copied from > criteria.md) #### Communication methods documented -One of the easiest ways to attract new contributors is making sure they know how -to reach you. +One of the easiest ways to attract new contributors is making sure they know how to reach you. We evaluate on the following: -- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked - from your website? +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? - Is there a direct link to your GitHub organization/repository? -- Are weekly/monthly project meetings documented? Is it clear how someone can - join those meetings? +- Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? - Are mailing lists documented? #### Beginner friendly issue backlog @@ -282,16 +203,13 @@ We evaluate on the following: We evaluate on the following: - Are docs issues well-triaged? -- Is there a clearly marked way for new contributors to make code or - documentation contributions (i.e. a “good first issue” label)? +- Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? - Are issues well-documented (i.e., more than just a title)? - Are issues maintained for staleness? #### New contributor getting started content -Open source is complex and projects have many processes to manage that. Are -processes easy to understand and written down so that new contributors can jump -in easily? +Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily? We evaluate on the following: @@ -309,8 +227,7 @@ We evaluate on the following: ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. +> AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. #### Communication methods documented @@ -324,14 +241,11 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside -the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ------------------------------------------- | -------------- | @@ -352,41 +266,28 @@ the project code. ### Comments -> AUTHOR NOTE: make any overall comments about the Website and documentation -> infrastructure here. +> AUTHOR NOTE: make any overall comments about the Website and documentation > infrastructure here. -The following sections contain brief assessments of each element of the Website -and documentation infrastructure rubric. +The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. -> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the website infrastructure criteria -> depend on the tools (static site generator, website framework and hosting, -> analytics tools, etc.) and processes (project CI, release procedures, -> governance, etc.) used to produce the documentation. (Criteria are copied from -> criteria.md) +> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet > these criteria. Keep in mind that much of the website infrastructure criteria > depend on the tools (static site generator, website framework and hosting, > analytics tools, etc.) and processes (project CI, release procedures, > governance, etc.) used to produce the documentation. (Criteria are copied from > criteria.md) #### Single-source requirement -Source files for _all website pages_ should reside in a single repo. Among other -problems, keeping source files in two places: +Source files for _all website pages_ should reside in a single repo. Among other problems, keeping source files in two places: - confuses contributors - requires you to keep two sources in sync - increases the likelihood of errors - 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][git-submodules]. +Ideally, all website files should be in the **website repo** itself. Alternatively, files should be brought into the website repo via [git submodules][git-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. +If a project chooses to keep source files in multiple repos, they need a clearly documented strategy for managing mirrored files and new contributions. #### Minimal website requirements -Listed here are the minimal website requirements for projects based on their -[maturity level][maturity-level], either incubating or graduated. (These are the -only two levels for which a tech docs analysis can be requested.) +Listed here are the minimal website requirements for projects based on their [maturity level][maturity-level], either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) @@ -400,16 +301,13 @@ only two levels for which a tech docs analysis can be requested.) -[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[maturity-level]: +[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules [maturity-level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [cncf-servicedesk]: https://servicedesk.cncf.io #### Usability, accessibility and devices -Most CNCF websites are accessed from mobile and other non-desktop devices at -least 10-20% of the time. Planning for this early in your website's design will -be much less effort than retrofitting a desktop-first design. +Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. - Is the website usable from mobile? - Are doc pages readable? @@ -432,25 +330,21 @@ It is up to each project to set their own guidelines. #### Branding and design -CNCF seeks to support enterprise-ready open source software. A key aspect of -this is branding and marketing. +CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing. We evaluate on the following: -- Is there an easily recognizable brand for the project (logo + color scheme) - clearly identifiable? +- 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? #### Case studies/social proof -One of the best ways to advertise an open source project is to show other -organizations using it. +One of the best ways to advertise an open source project is to show other organizations using it. We evaluate on the following: -- Are there case studies available for the project and are they documented on - the website? +- Are there case studies available for the project and are they documented on the website? - Are there user testimonials available? - Is there an active project blog? - Are there community talks for the project and are they present on the website? @@ -458,9 +352,7 @@ We evaluate on the following: #### 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 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. We evaluate on the following: @@ -478,13 +370,11 @@ We evaluate on the following: #### Maintenance planning -Website maintenance is an important part of project success, especially when -project maintainers aren’t web developers. +Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. We evaluate on the following: -- Is your website tooling well supported by the community (i.e., Hugo with the - Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) +- Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) - Are you actively cultivating website maintainers from within the community? - Are site build times reasonable? - Do site maintainers have adequate permissions? From 05b95516ca2a13e1e9523f50b20bf53372be4f52 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Sun, 29 Mar 2026 23:41:35 -0700 Subject: [PATCH 040/104] Update analysis.md Initial write-up of analysis Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 285 ++++++++++++++++++++---------- 1 file changed, 194 insertions(+), 91 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 8a320cf..e80b917 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,7 +10,7 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analyzes the effectiveness and completeness of the [Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. +This document is an analysis the effectiveness and completeness of the [Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. @@ -32,12 +32,13 @@ The Flatcar website and documentation are written in [Markdown, ReStructured Tex #### In scope -- Website: https://www.flatcar.org/ -- Documentation: https://www.flatcar.org/docs/latest -- Website repo: https://github.com/cncf/techdocs +- Website: +- Documentation: +- Website repo: #### Out of scope +Other Flatcar repos: , for any not listed in "In scope". ### How this document is organized @@ -72,11 +73,7 @@ This analysis measures documentation against CNCF project maturity standards, an ## Project documentation -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. - > AUTHOR NOTE: or - Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | -------------------------- | -------------- | @@ -88,65 +85,171 @@ Flatcar is a **graduated** project of CNCF. This means that the project should h ### Comments -> AUTHOR NOTE: make any overall comments about the Project Documentation here. +The following sections contain brief assessments of each element of the project documentation. + +The current Flatcar documentation table of contents defines the needed areas of knowledge to install and provision Flatcar, but it does not readily show the different paths for new users depending on their environment. + +The following comments regard the top-tier nodes in the current table of contents: + +- The top overview page contains headings with short paragraphs and links that provide additional views and categorization of Flatcar topics. These links are not necessarily parallel with the table of contents hierarchy. +- The "Installing" node Overview page introduces the needed guidance for the provisioning and configuration of Flatcar, but it also contains getting started code for a VM installation. That content is better served by a Getting Started node or the Learning Series node. +- The "Installing" node contains the large "Cloud Providers" node, that might be better as top tier node, same with "Bare Metal". The team agrees that "Community supported platforms" could be merged into the Cloud Providers node. The installation node should be primarily addressing all the new user paths, providing an installation roadmap or strategy. +The "Learning Series" node, introduced into the documentation recently, outlines the key steps for installing, configuring, and managing Flatcar conveying the life cycle. It would be good for the top nodes to have a similar flow. +- The "Provisioning Tools" title is descriptive, but its unclear how other areas of the docs relate to this section. +- The "Nebraska" node is about updates, but it should convey the functionality and its location is unusual prominence. +- The "Setup and Operations" node is too much of a wide net in its title. How does "setup" differ from installation? The node contains several important content areas that should be more discoverable, for instance: + - "Managing Clusters" might be better at a higher level because it's an initial evaluation of whether to deploy Flatcar. + - The Storage and Security nodes are typically at a higher level. + - The systemd is about core OS management. +- The "Container Runtimes" node is an expected node focused on containers and clusters. An argument could be made to elevate "Getting Started with Kubernetes" and "High Availability Kubernetes" to its own node, as Flatcar has its optimization benefits for Kubernetes deployment. +- The "Migrating from CoreOS" node might be better placed earlier or within an Installation node, as it is an installation scenario. +- The "Reference" node contains expected look-up information such as "Constance and IDs" and "Supply chain security mechanisms" but these sections could have better placement: + - "Integrations" could be incorporated into the Cloud Providers documentation. + - "Developer Guides" contains conceptual content typically not found in a Reference section, so "Developer Guides" or something more descriptive like "Flatcar Development Guides" should be a top-tier node. +- The "How to Contribute" node is well-placed has the expected content. + +The documentation also includes an FAQ, accessible from the top banner of the home page. It has some content that would be good to verify that its in the main docs, such as historical context and how images are updated. Conversely, there should be a few top-of-mind installation and support FAQ items derived from the docs. -The following sections contain brief assessments of each element of the Project -Documentation rubric. +Code blocks are different from other documentation sets as they are not bordered or have a different fill background, don't have a copy button, and the language is not noted. -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and > especially the technical documentation, meet these criteria. (Criteria are > copied from criteria.md) +New users might not be sure of the context for a given block of code. Is the Linux prompt in a VM, in a client computer, or in a CLI session with a cloud provider? Normally this can be deduced by the narrative, but starting a procedure with "In the VM window, use the following command to ..." or similar guidance. + +It should be noted that a new proposed structure is proposed by the team, with the top nodes as follows: + + Flatcar Concepts and Quick Start + Configuration and Provisioning + Deploying to Public Cloud, Private Cloud, and Bare Metal + Kubernetes + In-place updates and roll-backs + The Nebraska update server + Customizing and Extending the OS image + Troubleshooting + Developer Guides + Legacy Information + +Essentially all the pertinent areas of knowledge to install and run Flatcar have been identified and documented. Then just need to be better organized. The next step is to structure the documentation so that it meets these objectives: + +- The node and topic titles provide expected guidance, such as "Getting Started", with nodes and sections organized for precise purposes, rather than headings that serve as broad categories such as "Setup and Operations". +- The structure provides the expected flow and orientation of users so that they can identify a pathway for learning about and deploying Flatcar efficiently and optimally. +- The structure provides effective navigation and identification of the tools and technologies so that users efficiently learn about the ones they need to use. #### Information architecture The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: -- Is there high level conceptual/“About” content? Is the documentation feature complete? (i.e., each product feature is documented) - Are there step-by-step instructions (tasks, tutorials) documented for features? -- Are there any key features which are documented but missing task documentation? -- Is the “happy path”/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) -- If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) -- If the product exposes an API, is there a complete reference? -- Is content up to date and accurate? +##### Is there high-level conceptual or About content? -#### New user content +The current content is comprehensive on the key concepts needed for understanding the processes and technologies involved. It's just a matter of organizing discussion of the concepts to map to the user the path for installing and configuring Flatcar. + +- **Is the documentation feature complete?** + + Yes, given that Flatcar is essentially an operating system and new features and capabilities will be apparent and easily referenced. + +- **Are there step-by-step instructions (tasks, tutorials) documented for features?** + + Procedures, mainly invoking bash commands, are introduced informally and do not have the typical Microsoft style of numbered steps that read "Use the following command to ..." verbiage. It would be easy to rewrite for meet that conformity. + +- **Are there any key features which are documented but missing task documentation?** + + Not so much regarding features, but there are tasks in using provisioning tools where step-by-step guidance would be appreciated. + +- **Are tasks clearly named according to user goals providing a happy path for users to get their tasks accomplished?** + + Not currently. But the needed content areas are established and just need to be coordinated into a "Flatcar installation roadmap" for most paths. + +- **If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ)** + + There is an FAQ that needs updating. + +- **If the product exposes an API, is there a complete reference?** + + There is a Developer Guide for building Flatcar Container Linux from source and/or in modifying the OS. The SDK is a containerized Software Development Kit that enables developers to customize and build their own Flatcar Container Linux OS images. + + The SDK is not an API with function calls, but rather a kit of scripts and tools. + +##### New user content New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: -- Is “getting started” clearly labeled? (“Getting started”, “Installation”, “First steps”, etc.) -- Is installation documented step-by-step? -- If needed, are multiple OSes documented? -- Do users know where to go after reading the getting started guide? -- Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? -- Is there sample code or other example content that can easily be copy-pasted? +- **Is “getting started” or similar clearly labeled?** -#### Content maintainability & site mechanics +The "Learning Series" is a well-documented getting started guide. There is a Heading 3 heading "Getting started" in the overview. + +- **Is installation documented step-by-step?** + +Procedures are not formal step-by-steps, but rather sufficient descriptions of the purpose and result of running the provided code example. + +Even if the new user does not know anything about the technologies, it can still be logical and understandable by looking up terms. + +- **If needed, are multiple OSes documented?** + +Users are typically running a Linux machine, or a VM running on Windows or MacOS. It would be beneficial to acquaint the user with any client OS guidance, particularly when installing tools and images. + +- **Do users know where to go after reading the getting started guide?** + +Intuitively perhaps, as the Learning Services provides sufficient content to get Flatcar instances running. It would be good to have listings of next steps for the various deployment scenarios. + +- **Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture?** + +Other than being a top level node in the table of contents, no. + +- **Is there sample code or other example content that can easily be copy-pasted?** + +Yes, most pages have code samples, but currently the UI does not show code example blocks with copy buttons. The code is simply in a different font. + +##### Content maintainability & site mechanics As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. We evaluate on the following: -- Is your documentation searchable? -- Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? -- Do you have a clearly documented method for versioning your content? +- **Is your documentation searchable?** -#### Content creation processes +Yes, the home page has a search bar where any results populate a dropdown for selection. + +- **Are you planning for localization/internationalization?** + +There are currently no plans for localization. + +- **Do you have a clearly documented method for versioning your content?** + +Being an incubating project, the content is not versioned at this time. + +##### Content creation processes Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. We evaluate on the following: -- Is there a clearly documented (ongoing) contribution process for documentation? -- Does your code release process account for documentation creation & updates? -- Who reviews and approves documentation pull requests? -- Does the website have a clear owner/maintainer? +- **Is there a clearly documented (ongoing) contribution process for documentation?** -#### Inclusive language +Yes. There is a 'How to contribute' node with guidance for using the GitHub repository, formatting, and style. + +- **Does your code release process account for documentation creation & updates?** + +Supported, but not a formalized process at this time. + +- **Who reviews and approves documentation pull requests?** + +Jan Bronicki + +- **Does the website have a clear owner/maintainer?** + +Jan Bronicki + +##### Inclusive language Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: -- Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the - [Inclusive Naming Initiative](https://inclusivenaming.org) website? -- Does the project use language like "simple", "easy", etc.? +- **Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website?** + +The 175 hits were "master", "disable", "abort", and "man in the middle". Of those only "abort" would necessitate a fix on eight occurrences. + +- **Does the project use language like "simple", "easy", etc.?** + +No, the complexity of the content is a given, and the content assumes a level of sophistication where such verbiage would be suspicious. ### Recommendations @@ -193,29 +296,29 @@ One of the easiest ways to attract new contributors is making sure they know how We evaluate on the following: -- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? -- Is there a direct link to your GitHub organization/repository? -- Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? -- Are mailing lists documented? +- **Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?** +- **Is there a direct link to your GitHub organization/repository?** +- **Are weekly/monthly project meetings documented?** Is it clear how someone can join those meetings?** +- **Are mailing lists documented?** #### Beginner friendly issue backlog We evaluate on the following: -- Are docs issues well-triaged? -- Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? -- Are issues well-documented (i.e., more than just a title)? -- Are issues maintained for staleness? +- **Are docs issues well-triaged?** +- **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** +- **Are issues well-documented (i.e., more than just a title)?** +- **Are issues maintained for staleness?** #### New contributor getting started content -Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily? +Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily?** We evaluate on the following: -- Do you have a community repository or section on your website? -- Is there a document specifically for new contributors/your first contribution? -- Do new users know where to get help? +- **Do you have a community repository or section on your website?** +- **Is there a document specifically for new contributors/your first contribution?** +- **Do new users know where to get help?** #### Project governance documentation @@ -223,7 +326,7 @@ One of the CNCF’s core project values is open governance. We evaluate on the following: -- Is project governance clearly documented? +- **Is project governance clearly documented?** ### Recommendations @@ -276,10 +379,10 @@ The following sections contain brief assessments of each element of the Website Source files for _all website pages_ should reside in a single repo. Among other problems, keeping source files in two places: -- confuses contributors -- requires you to keep two sources in sync -- increases the likelihood of errors -- makes it more complicated to generate the documentation from source files +- **confuses contributors +- **requires you to keep two sources in sync +- **increases the likelihood of errors +- **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][git-submodules]. @@ -301,28 +404,28 @@ Listed here are the minimal website requirements for projects based on their [ma -[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules [maturity-level]: - https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations -[cncf-servicedesk]: https://servicedesk.cncf.io +[git-submodules]: [maturity-level]: + +[cncf-servicedesk]: #### Usability, accessibility and devices Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. -- Is the website usable from mobile? -- Are doc pages readable? -- Are all / most website features accessible from mobile -- such as the top-nav, - site search and in-page table of contents? -- Might a [mobile-first] design make sense for your project? +- **Is the website usable from mobile?** +- **Are doc pages readable?** +- **Are all / most website features accessible from mobile -- **such as the top-nav, + site search and in-page table of contents?** +- **Might a [mobile-first] design make sense for your project?** [mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first Plan for suitable [accessibility][] measures for your website. For example: -- Are color contrasts significant enough for color-impaired readers? -- Are most website features usable using a keyboard only? -- Does text-to-speech offer listeners a good experience? +- **Are color contrasts significant enough for color-impaired readers?** +- **Are most website features usable using a keyboard only?** +- **Does text-to-speech offer listeners a good experience?** It is up to each project to set their own guidelines. @@ -334,9 +437,9 @@ CNCF seeks to support enterprise-ready open source software. A key aspect of thi 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 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?** #### Case studies/social proof @@ -344,11 +447,11 @@ One of the best ways to advertise an open source project is to show other organi We evaluate on the following: -- Are there case studies available for the project and are they documented on the website? -- Are there user testimonials available? -- Is there an active project blog? -- Are there community talks for the project and are they present on the website? -- Is there a logo wall of users/participating organizations? +- **Are there case studies available for the project and are they documented on the website?** +- **Are there user testimonials available?** +- **Is there an active project blog?** +- **Are there community talks for the project and are they present on the website?** +- **Is there a logo wall of users/participating organizations?** #### SEO, Analytics and site-local search @@ -356,16 +459,16 @@ SEO helps users find your project and it's documentation, and analytics helps yo We evaluate on the following: -- Analytics: - - Is analytics enabled for the production server? - - Is analytics disabled for all other deploys? - - If your project used Google Analytics, have you migrated to GA4? - - Can Page-not-found (404) reports easily be generated from you site - analytics? Provide a sample of the site's current top-10 404s. -- Is site indexing supported for the production server, while disabled for - website previews and builds for non-default branches? -- Is local intra-site search available from the website? -- Are the current custodian(s) of the following accounts clearly documented: +- **Analytics: + - **Is analytics enabled for the production server?** + - **Is analytics disabled for all other deploys?** + - **If your project used Google Analytics, have you migrated to GA4?** + - **Can Page-not-found (404) reports easily be generated from you site + analytics?** Provide a sample of the site's current top-10 404s. +- **Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches?** +- **Is local intra-site search available from the website?** +- **Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) #### Maintenance planning @@ -374,15 +477,15 @@ Website maintenance is an important part of project success, especially when pro We evaluate on the following: -- Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) -- Are you actively cultivating website maintainers from within the community? -- Are site build times reasonable? -- Do site maintainers have adequate permissions? +- **Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?**) +- **Are you actively cultivating website maintainers from within the community?** +- **Are site build times reasonable?** +- **Do site maintainers have adequate permissions?** #### Other -- Is your website accessible via HTTPS? -- Does HTTP access, if any, redirect to HTTPS? +- **Is your website accessible via HTTPS?** +- **Does HTTP access, if any, redirect to HTTPS?** ### Recommendations From 1075865f17f2d28c743728933f3e12801174cfd4 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Sun, 29 Mar 2026 23:50:04 -0700 Subject: [PATCH 041/104] Update analysis.md Spelling fixes Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index e80b917..d7959cf 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -231,11 +231,11 @@ Supported, but not a formalized process at this time. - **Who reviews and approves documentation pull requests?** -Jan Bronicki +Team members are determined. - **Does the website have a clear owner/maintainer?** -Jan Bronicki +Team members are determined. ##### Inclusive language From 2fff7f2dc0eed0cea6d06163de2d0947dd95d0aa Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 00:01:42 -0700 Subject: [PATCH 042/104] Update index.md Removed dead link Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/analytics/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/analytics/index.md b/docs/analytics/index.md index 9567cbb..05a972b 100644 --- a/docs/analytics/index.md +++ b/docs/analytics/index.md @@ -19,8 +19,6 @@ title: Analytics > Analytics to GA4, see > [Migrating Universal to Google Analytics 4](ua-to-ga4.md). -[adding analytics]: - https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics [CNCF sandbox]: https://github.com/cncf/sandbox [docsy]: https://www.docsy.dev [ga4]: https://support.google.com/analytics/answer/10089681 From 34f1cc6f20c0f755fc366da9a43b68a88e430ac8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 00:17:44 -0700 Subject: [PATCH 043/104] Update ua-to-ga4.md Removed dead link Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/analytics/ua-to-ga4.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/analytics/ua-to-ga4.md b/docs/analytics/ua-to-ga4.md index 3cb8336..4ad3736 100644 --- a/docs/analytics/ua-to-ga4.md +++ b/docs/analytics/ua-to-ga4.md @@ -170,8 +170,6 @@ that your project is using. [add gtag.js to your site]: https://developers.google.com/analytics/devguides/collection/gtagjs/ -[adding analytics]: - https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics [analytics.js]: https://support.google.com/analytics/answer/10268458 [connected]: https://support.google.com/analytics/answer/9973999 [docsy]: https://www.docsy.dev From 14cd531de60a3af7b16ea0c7d69ef276c6d8acb8 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 24 Feb 2026 11:43:57 +0300 Subject: [PATCH 044/104] chore: Add a GH workflow to trigger contribute site Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- .../workflows/trigger-contribute-site-netlify.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .github/workflows/trigger-contribute-site-netlify.yml diff --git a/.github/workflows/trigger-contribute-site-netlify.yml b/.github/workflows/trigger-contribute-site-netlify.yml new file mode 100644 index 0000000..af8e923 --- /dev/null +++ b/.github/workflows/trigger-contribute-site-netlify.yml @@ -0,0 +1,13 @@ +name: Trigger contribute-site Netlify build + +on: + push: + branches: [main] + +jobs: + trigger: + runs-on: ubuntu-latest + steps: + - name: Call Netlify build hook + run: | + curl -sS -X POST "${{ secrets.NETLIFY_CONTRIBUTE_SITE_BUILD_HOOK }}" \ No newline at end of file From 7d3b2cdbbaf57b598a2bcc6add808cedc2ce41e3 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 24 Feb 2026 11:48:09 +0300 Subject: [PATCH 045/104] chore: prettify code Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- .github/workflows/trigger-contribute-site-netlify.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/trigger-contribute-site-netlify.yml b/.github/workflows/trigger-contribute-site-netlify.yml index af8e923..db81972 100644 --- a/.github/workflows/trigger-contribute-site-netlify.yml +++ b/.github/workflows/trigger-contribute-site-netlify.yml @@ -10,4 +10,4 @@ jobs: steps: - name: Call Netlify build hook run: | - curl -sS -X POST "${{ secrets.NETLIFY_CONTRIBUTE_SITE_BUILD_HOOK }}" \ No newline at end of file + curl -sS -X POST "${{ secrets.NETLIFY_CONTRIBUTE_SITE_BUILD_HOOK }}" From ce3aac412ac6c49815c3db596c101befa1a9f8d4 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 3 Mar 2026 15:48:12 +0000 Subject: [PATCH 046/104] chore: move info from top level README to docs readme Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index 9f616fb..88b8685 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,8 +3,60 @@ title: CNCF Techdocs how-tos sidebar_position: 1 --- -# CNCF Techdocs how-tos +# CNCF TechDocs -This section contains documentation on how the CNCF TechDocs team does things. -While its intent is for the CNCF TechDocs team's use, we encourage project -maintainers to use these documents if you find them helpful. +This site contains resources provided by the CNCF Technical Documentation team, +including: + +- Docs about building websites and developing technical documentation, + including recommended tools, best practices, how-tos, and evaluation + checklists. It provides specific guidelines for: + - Setting up and maintaining a documentation website. + - Writing technical documentation for a project. + - Seeking assistance from the CNCF TechDocs community. + - [Analyzing project documentation](./analysis). +- [Analyses](./analyses): a collection of documentation analyses of CNCF projects + performed by the TechDocs team. + +## TechDocs Q&A + +The CNCF TechDocs team holds a [Zoom meeting][] to answer questions and discuss +anything to do with documentation. Meetings are held on the [fourth Wednesday of +every month at 8am Pacific time][date-time]. + +- [Zoom meeting][] link +- [Meeting notes][] + +> Formerly called _Office Hours_, TechDocs Q&A started on September +> 30, 2020. + +## Assistance program for technical documentation + +The TechDocs team can help CNCF projects analyze and improve their +documentation. For details, see the TechDocs +[assistance program](./assistance.md). + +## CNCF TechDocs team + +The full-time staff of the team is: + +- [Daniel Krook](https://github.com/krook) - Senior director of developer + experience, CNCF +- [Nate W.](https://github.com/nate-double-u) - Head of mentoring & + documentation, CNCF +- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead +- [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate + +Consultants and volunteers also contribute to CNCF TechDocs efforts. + +## Licenses + +- Documentation: [CC-BY-4.0](LICENSE) +- Code: [Apache-2.0](LICENSE-CODE) + +[date-time]: + https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours +[Meeting notes]: + https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/ +[Zoom meeting]: + https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e From be93e59eac36a726d699f0e6914a06751cdc531e Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 3 Mar 2026 15:59:43 +0000 Subject: [PATCH 047/104] chore: fix CI errors Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- .cspell.yml | 4 ++++ docs/index.md | 12 ++++++------ 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index c13d3e9..0fa4166 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -21,6 +21,7 @@ ignorePaths: # - CodeBlock words: - backstore + - Chalin - CLOTributor - CNCF - Docsy @@ -32,9 +33,12 @@ words: - mkdocs - nate - nvmrc + - Obasi - subpages - techdocs - toolkits - toto - triaging + - Uchechukwu + - webdev - Welsch diff --git a/docs/index.md b/docs/index.md index 88b8685..abda93f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,15 +8,15 @@ sidebar_position: 1 This site contains resources provided by the CNCF Technical Documentation team, including: -- Docs about building websites and developing technical documentation, - including recommended tools, best practices, how-tos, and evaluation - checklists. It provides specific guidelines for: +- Docs about building websites and developing technical documentation, including + recommended tools, best practices, how-tos, and evaluation checklists. It + provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](./analysis). -- [Analyses](./analyses): a collection of documentation analyses of CNCF projects - performed by the TechDocs team. +- [Analyses](./analyses): a collection of documentation analyses of CNCF + projects performed by the TechDocs team. ## TechDocs Q&A @@ -44,7 +44,7 @@ The full-time staff of the team is: experience, CNCF - [Nate W.](https://github.com/nate-double-u) - Head of mentoring & documentation, CNCF -- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead +- [Patrice Chalin](https://github.com/chalin) - Senior TechDocs & webdev lead - [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate Consultants and volunteers also contribute to CNCF TechDocs efforts. From 04e67cf6b0ba1fcd8c2b1adc22d6cccab5a5a9e3 Mon Sep 17 00:00:00 2001 From: Uchechukwu Obasi Date: Tue, 3 Mar 2026 16:37:47 +0000 Subject: [PATCH 048/104] chore: update all analyses to use correct docusaurus tags system (#340) * chore: update all analyses to use correct docusaurus tags system Signed-off-by: thisisobate * chore: CI fix Signed-off-by: thisisobate --------- Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- .cspell.yml | 2 ++ analyses/2021/contour/analysis.md | 1 + analyses/2021/fluxcd/analysis.md | 1 + analyses/2021/krator/analysis.md | 1 + analyses/2021/kubernetes-gateway-api/analysis.md | 1 + analyses/2021/notary/analysis.md | 1 + analyses/2021/tremor/analysis.md | 1 + analyses/2023/backstage/backstage-glossary.md | 1 + analyses/2023/backstage/backstage-insights-summary.md | 1 + analyses/2023/backstage/backstage-issues.md | 1 + analyses/2023/backstage/user-roles.md | 1 + analyses/2023/etcd/etcd-issues.md | 1 + analyses/2023/in-toto/in-toto-analysis.md | 1 + analyses/2023/in-toto/in-toto-doc-issues.md | 1 + analyses/2023/in-toto/in-toto-implementation.md | 1 + analyses/2023/in-toto/index.md | 1 + analyses/2023/in-toto/survey-of-existing-doc.md | 1 + analyses/2023/porter/analysis.md | 1 + analyses/2024/TUF/implementation.md | 1 + analyses/2024/TUF/index.md | 1 + analyses/2024/TUF/issues.md | 1 + analyses/2024/keda/keda-analysis.md | 1 + analyses/2024/keda/keda-implementation.md | 1 + analyses/2024/keda/keda-issues.md | 1 + analyses/2024/litmuschaos/litmuschaos-issues.md | 1 + analyses/2025/knative/analysis.md | 2 +- analyses/2025/knative/issues.md | 2 +- analyses/2025/vitess/analysis.md | 2 +- analyses/index.md | 1 + 29 files changed, 30 insertions(+), 3 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 0fa4166..2af4e9b 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -26,9 +26,11 @@ words: - CNCF - Docsy - dwelsch + - fluxcd - keda - knative - kedacore + - krator - krook - mkdocs - nate diff --git a/analyses/2021/contour/analysis.md b/analyses/2021/contour/analysis.md index 4c20b34..eca478c 100644 --- a/analyses/2021/contour/analysis.md +++ b/analyses/2021/contour/analysis.md @@ -1,5 +1,6 @@ --- title: Docs assessment +tags: [contour] cSpell:ignore: Horgan celestehorgan hashlinks --- diff --git a/analyses/2021/fluxcd/analysis.md b/analyses/2021/fluxcd/analysis.md index d86bac6..f78270e 100644 --- a/analyses/2021/fluxcd/analysis.md +++ b/analyses/2021/fluxcd/analysis.md @@ -1,5 +1,6 @@ --- title: Assessment template +tags: [fluxcd] cSpell:ignore: celestehorgan Horgan --- diff --git a/analyses/2021/krator/analysis.md b/analyses/2021/krator/analysis.md index 5186a46..f4f7270 100644 --- a/analyses/2021/krator/analysis.md +++ b/analyses/2021/krator/analysis.md @@ -1,5 +1,6 @@ --- title: Krator Docs assessment +tags: [krator] cSpell:ignore: Krator celestehorgan CODEOWNERS --- diff --git a/analyses/2021/kubernetes-gateway-api/analysis.md b/analyses/2021/kubernetes-gateway-api/analysis.md index 073165d..372a53d 100644 --- a/analyses/2021/kubernetes-gateway-api/analysis.md +++ b/analyses/2021/kubernetes-gateway-api/analysis.md @@ -1,5 +1,6 @@ --- title: 'Assessment: Project Kubernetes Gateway API' +tags: [kubernetes-gateway-api] cSpell:ignore: Meha Bhalodiya mehabhalodiya kubernetes --- diff --git a/analyses/2021/notary/analysis.md b/analyses/2021/notary/analysis.md index bbadd5b..76634b1 100644 --- a/analyses/2021/notary/analysis.md +++ b/analyses/2021/notary/analysis.md @@ -1,5 +1,6 @@ --- title: Notary Project Docs Assessment +tags: [notary] cSpell:ignore: docset notaryproject celestehorgan --- diff --git a/analyses/2021/tremor/analysis.md b/analyses/2021/tremor/analysis.md index 53fd6fd..e84ef35 100644 --- a/analyses/2021/tremor/analysis.md +++ b/analyses/2021/tremor/analysis.md @@ -1,5 +1,6 @@ --- title: 'Assessment: Project Tremor' +tags: [tremor] cSpell:ignore: Horgan onramps offramps LLDB Wayfair --- diff --git a/analyses/2023/backstage/backstage-glossary.md b/analyses/2023/backstage/backstage-glossary.md index 91c859f..74a6f46 100644 --- a/analyses/2023/backstage/backstage-glossary.md +++ b/analyses/2023/backstage/backstage-glossary.md @@ -1,5 +1,6 @@ --- title: Backstage Glossary +tags: [backstage] --- # Backstage Glossary diff --git a/analyses/2023/backstage/backstage-insights-summary.md b/analyses/2023/backstage/backstage-insights-summary.md index ace5664..edf3cf3 100644 --- a/analyses/2023/backstage/backstage-insights-summary.md +++ b/analyses/2023/backstage/backstage-insights-summary.md @@ -1,5 +1,6 @@ --- title: Backstage Insights +tags: [backstage] cSpell:ignore: flipside --- diff --git a/analyses/2023/backstage/backstage-issues.md b/analyses/2023/backstage/backstage-issues.md index 2e0c52a..df7056f 100644 --- a/analyses/2023/backstage/backstage-issues.md +++ b/analyses/2023/backstage/backstage-issues.md @@ -1,5 +1,6 @@ --- title: Backstage umbrella issue +tags: [backstage] --- # Backstage umbrella issue diff --git a/analyses/2023/backstage/user-roles.md b/analyses/2023/backstage/user-roles.md index d44fd81..d1869b5 100644 --- a/analyses/2023/backstage/user-roles.md +++ b/analyses/2023/backstage/user-roles.md @@ -1,5 +1,6 @@ --- title: Backstage User Roles for Doc +tags: [backstage] --- # Backstage User Roles for Doc diff --git a/analyses/2023/etcd/etcd-issues.md b/analyses/2023/etcd/etcd-issues.md index 123c5b8..7683394 100644 --- a/analyses/2023/etcd/etcd-issues.md +++ b/analyses/2023/etcd/etcd-issues.md @@ -1,5 +1,6 @@ --- title: etcd Umbrella Issue +tags: [etcd] cSpell:ignore: reconf --- diff --git a/analyses/2023/in-toto/in-toto-analysis.md b/analyses/2023/in-toto/in-toto-analysis.md index be8d5b5..dca0bd5 100644 --- a/analyses/2023/in-toto/in-toto-analysis.md +++ b/analyses/2023/in-toto/in-toto-analysis.md @@ -1,5 +1,6 @@ --- title: Analysis of Existing Documentation +tags: [in-toto] --- # Analysis of Existing Documentation diff --git a/analyses/2023/in-toto/in-toto-doc-issues.md b/analyses/2023/in-toto/in-toto-doc-issues.md index 29f61b9..f599d1d 100644 --- a/analyses/2023/in-toto/in-toto-doc-issues.md +++ b/analyses/2023/in-toto/in-toto-doc-issues.md @@ -1,5 +1,6 @@ --- title: Documentation Issues +tags: [in-toto] --- # Documentation Issues diff --git a/analyses/2023/in-toto/in-toto-implementation.md b/analyses/2023/in-toto/in-toto-implementation.md index 06ac4f3..5ec2ab2 100644 --- a/analyses/2023/in-toto/in-toto-implementation.md +++ b/analyses/2023/in-toto/in-toto-implementation.md @@ -1,5 +1,6 @@ --- title: Implementation +tags: [in-toto] cSpell:ignore: roadmaps Cappos --- diff --git a/analyses/2023/in-toto/index.md b/analyses/2023/in-toto/index.md index 818c644..d725cee 100644 --- a/analyses/2023/in-toto/index.md +++ b/analyses/2023/in-toto/index.md @@ -1,5 +1,6 @@ --- title: README +tags: [in-toto] --- # README diff --git a/analyses/2023/in-toto/survey-of-existing-doc.md b/analyses/2023/in-toto/survey-of-existing-doc.md index 5405ccc..adb33cb 100644 --- a/analyses/2023/in-toto/survey-of-existing-doc.md +++ b/analyses/2023/in-toto/survey-of-existing-doc.md @@ -1,5 +1,6 @@ --- title: Survey of existing documentation as of 09/2023 +tags: [in-toto] --- # Survey of existing documentation as of 09/2023 diff --git a/analyses/2023/porter/analysis.md b/analyses/2023/porter/analysis.md index 34bec4c..c2050c5 100644 --- a/analyses/2023/porter/analysis.md +++ b/analyses/2023/porter/analysis.md @@ -1,5 +1,6 @@ --- title: Porter Docs Analysis +tags: [porter] cSpell:ignore: Uchechukwu Obasi --- diff --git a/analyses/2024/TUF/implementation.md b/analyses/2024/TUF/implementation.md index fb21cfa..f0ed54b 100644 --- a/analyses/2024/TUF/implementation.md +++ b/analyses/2024/TUF/implementation.md @@ -1,5 +1,6 @@ --- title: Implementing TUF Doc Improvements +tags: [TUF] cSpell:ignore: RSTUF --- diff --git a/analyses/2024/TUF/index.md b/analyses/2024/TUF/index.md index 81e3de6..b0df22f 100644 --- a/analyses/2024/TUF/index.md +++ b/analyses/2024/TUF/index.md @@ -1,5 +1,6 @@ --- title: TUF Documentation Analysis +tags: [TUF] cSpell:ignore: theupdateframework --- diff --git a/analyses/2024/TUF/issues.md b/analyses/2024/TUF/issues.md index 3faef04..5676f04 100644 --- a/analyses/2024/TUF/issues.md +++ b/analyses/2024/TUF/issues.md @@ -1,5 +1,6 @@ --- title: TUF Issue +tags: [TUF] cSpell:ignore: theupdateframework --- diff --git a/analyses/2024/keda/keda-analysis.md b/analyses/2024/keda/keda-analysis.md index e327861..cb4517d 100644 --- a/analyses/2024/keda/keda-analysis.md +++ b/analyses/2024/keda/keda-analysis.md @@ -1,5 +1,6 @@ --- title: KEDA Documentation Analysis +tags: [KEDA] created: 2024-02-23 modified: 2024-04-09 author: Dave Welsch (@dwelsch-esi) diff --git a/analyses/2024/keda/keda-implementation.md b/analyses/2024/keda/keda-implementation.md index 695b6cd..46e5bc3 100644 --- a/analyses/2024/keda/keda-implementation.md +++ b/analyses/2024/keda/keda-implementation.md @@ -1,5 +1,6 @@ --- title: Implementing KEDA Doc Improvements +tags: [KEDA] --- diff --git a/analyses/2024/keda/keda-issues.md b/analyses/2024/keda/keda-issues.md index 5eb497b..7b048c8 100644 --- a/analyses/2024/keda/keda-issues.md +++ b/analyses/2024/keda/keda-issues.md @@ -1,5 +1,6 @@ --- title: KEDA Umbrella Issue +tags: [KEDA] cSpell:ignore: externalscaler findability --- diff --git a/analyses/2024/litmuschaos/litmuschaos-issues.md b/analyses/2024/litmuschaos/litmuschaos-issues.md index f0b38b9..34acfde 100644 --- a/analyses/2024/litmuschaos/litmuschaos-issues.md +++ b/analyses/2024/litmuschaos/litmuschaos-issues.md @@ -1,5 +1,6 @@ --- title: Litmus Chaos Issue +tags: [LitmusChaos] cSpell:ignore: litmuschaos ChaoCenter --- diff --git a/analyses/2025/knative/analysis.md b/analyses/2025/knative/analysis.md index 3afc975..ea6c3b0 100644 --- a/analyses/2025/knative/analysis.md +++ b/analyses/2025/knative/analysis.md @@ -1,6 +1,6 @@ --- title: Knative Documentation Analysis -tags: Knative +tags: [Knative] created: 2025-07-25 modified: 2025-07-25 author: Dave Welsch (@dwelsch-esi) diff --git a/analyses/2025/knative/issues.md b/analyses/2025/knative/issues.md index fc040ce..c3314a1 100644 --- a/analyses/2025/knative/issues.md +++ b/analyses/2025/knative/issues.md @@ -1,6 +1,6 @@ --- title: Knative Issues -tags: Knative +tags: [Knative] created: 2025-07-28 modified: 2025-07-28 author: Dave Welsch (@dwelsch-esi) diff --git a/analyses/2025/vitess/analysis.md b/analyses/2025/vitess/analysis.md index 6f622b4..691e9ca 100644 --- a/analyses/2025/vitess/analysis.md +++ b/analyses/2025/vitess/analysis.md @@ -1,6 +1,6 @@ --- title: Vitess Documentation Analysis -tags: Vitess +tags: [Vitess] created: 2025-02-19 modified: 2025-02-19 author: Dave Welsch (dwelsch-esi) diff --git a/analyses/index.md b/analyses/index.md index 8f3ba9e..e6f50b4 100644 --- a/analyses/index.md +++ b/analyses/index.md @@ -1,5 +1,6 @@ --- title: TechDocs Analysis for CNCF Projects +tags: [analyses] --- From 0e979f80bc3f781490b8c73d45ffaf7700eefe43 Mon Sep 17 00:00:00 2001 From: Uchechukwu Obasi Date: Tue, 3 Mar 2026 18:27:50 +0000 Subject: [PATCH 049/104] chore: fix MDX related errors for vitess and knative analyses (#341) Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2025/knative/analysis.md | 4 ++-- analyses/2025/vitess/analysis.md | 25 ++++++++++++++----------- 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/analyses/2025/knative/analysis.md b/analyses/2025/knative/analysis.md index ea6c3b0..106f390 100644 --- a/analyses/2025/knative/analysis.md +++ b/analyses/2025/knative/analysis.md @@ -60,8 +60,8 @@ is stored on the knative/docs GitHub repo. #### Out of scope -- Other Knative repos: https://github.com/knative/\, for any \ not - listed in "In scope". +- Other Knative repos: `https://github.com/knative/REPO_NAME`, for any + `REPO_NAME` not listed in "In scope". ### How this document is organized diff --git a/analyses/2025/vitess/analysis.md b/analyses/2025/vitess/analysis.md index 691e9ca..d721b18 100644 --- a/analyses/2025/vitess/analysis.md +++ b/analyses/2025/vitess/analysis.md @@ -51,15 +51,18 @@ code is stored in its own repository in the Vitess GitHub project. #### In scope -- Website: -- Documentation: -- Website repo: -- Project repo (for reference): +- Website: [https://vitess.io/](https://vitess.io/) +- Documentation: [https://vitess.io/docs/](https://vitess.io/docs/) +- Website repo: + [https://github.com/vitessio/website](https://github.com/vitessio/website) +- Project repo (for reference): + [https://github.com/vitessio](https://github.com/vitessio) #### Out of scope -- Other Vitess repos: (In general, other Vitess - code repos are out of scope) +- Other Vitess repos: + [https://github.com/vitessio/](https://github.com/vitessio/) (In general, + other Vitess code repos are out of scope) ### How this document is organized @@ -482,11 +485,11 @@ Also on the Global TopoServer page, by the way: > --topo_global_root=/vitess/global > ``` > -> To avoid repetition we will use in our examples to signify the +> To avoid repetition we will use `topo_flags` in our examples to signify the > above flags. -Remove this. The `` placeholder does not seem to have been -implemented. There are no mentions of `` elsewhere in the +Remove this. The `topo_flags` placeholder does not seem to have been +implemented. There are no mentions of `topo_flags` elsewhere in the documentation, and in any case each would have to refer back to this page. In the FAQ: Rename the questions into concise headings when you consolidate the @@ -546,8 +549,8 @@ Here's how I'd rewrite it, defining placeholders for the parameters: > > where: > -> - is the root directory of the server installation -> - is the IP address of the topo server +> - `root_dir` is the root directory of the server installation +> - `cell_topo_addr` is the IP address of the topo server (or whatever the actual descriptions of the parameters are.) From c9ddec958c85af1984094accb61d0cba6a9e4c46 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Thu, 5 Mar 2026 11:25:28 +0000 Subject: [PATCH 050/104] chore: nit fix Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index abda93f..7668554 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,8 +15,9 @@ including: - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](./analysis). -- [Analyses](./analyses): a collection of documentation analyses of CNCF - projects performed by the TechDocs team. + +It also contains a collection of documentation analyses of CNCF projects +performed by the TechDocs team. ## TechDocs Q&A From 9e0fd9cf1c068997988987dd595f257751613d0a Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 10 Mar 2026 15:34:32 +0000 Subject: [PATCH 051/104] chore: nit fix Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 7668554..6d837e3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,7 +14,7 @@ including: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - - [Analyzing project documentation](./analysis). + - Analyzing project documentation. It also contains a collection of documentation analyses of CNCF projects performed by the TechDocs team. From d546d37f0216801f0f29910410c8c7cd29be6605 Mon Sep 17 00:00:00 2001 From: Uchechukwu Obasi Date: Tue, 17 Mar 2026 23:06:03 +0000 Subject: [PATCH 052/104] Chore: Fix all broken links outlined in issue description (#345) * Chore: Fix all broken links outlined in issue description Signed-off-by: thisisobate * chore: format files Signed-off-by: thisisobate * chore: fix markdown error Signed-off-by: thisisobate * chore: fix markdown error Signed-off-by: thisisobate * chore: fix markdown error again Signed-off-by: thisisobate * chore: fix link checker in CI Signed-off-by: thisisobate * chore: add backsticks to link Signed-off-by: thisisobate --------- Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- .htmltest.yml | 2 ++ analyses/2023/etcd/etcd-analysis.md | 9 +++++---- analyses/2025/knative/issues.md | 4 ++-- docs/analysis/templates/analysis.md | 11 +++++------ docs/index.md | 4 ++-- docs/repo-setup.md | 5 +++-- docs/website-guidelines-checklist.md | 2 +- 7 files changed, 20 insertions(+), 17 deletions(-) diff --git a/.htmltest.yml b/.htmltest.yml index 84e17fd..ea46cd5 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -7,6 +7,8 @@ IgnoreInternalURLs: # list of paths IgnoreURLs: # list of regexes of URLs or path to be ignored - ^https?://localhost - \?no-link-check + - _PROJECT-WEBSITE_ + - _PROJECT-DOC-URL_ # FIXME: temporary ignore rules - assistance\.md - LICENSE diff --git a/analyses/2023/etcd/etcd-analysis.md b/analyses/2023/etcd/etcd-analysis.md index a9d7818..f8a0614 100644 --- a/analyses/2023/etcd/etcd-analysis.md +++ b/analyses/2023/etcd/etcd-analysis.md @@ -55,7 +55,7 @@ Netlify platform. The site's code is stored on the etcd GitHub repo. **Out of scope:** -- Other etcd repos: https://github.com/etcd-io/* +- Other etcd repos: `https://github.com/etcd-io/*` ## How this document is organized @@ -299,9 +299,10 @@ The website has a Those maintainer **responsible for approving** documentation PRs are listed as "approvers". -The website repo [README](../../README.md) is out of date. For example, -instructions for building the website state that the local build starts the -server on `localhost:8888`. It's actually `localhost:1313`. +The website repo +[README](https://github.com/etcd-io/website/blob/main/README.md) is out of date. +For example, instructions for building the website state that the local build +starts the server on `localhost:8888`. It's actually `localhost:1313`. ### Inclusive language diff --git a/analyses/2025/knative/issues.md b/analyses/2025/knative/issues.md index c3314a1..3e74e1a 100644 --- a/analyses/2025/knative/issues.md +++ b/analyses/2025/knative/issues.md @@ -196,7 +196,7 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. Related material in the current doc: -- https://github.com/knative/install +- https://knative.dev/docs/install/ Suggested changes: @@ -665,7 +665,7 @@ start by looking at the [mkdocs config file]. https://github.com/knative/docs/blob/main/contribute-to-docs/style-guide/voice-and-language.md#avoid-statements-that-will-soon-be-out-of-date [Install Knative using quickstart]: https://knative.dev/docs/install/quickstart-install/ -[Installing Knative]: https://github.com/knative/install +[Installing Knative]: https://knative.dev/docs/install/ [Installing the Knative CLI]: https://knative.dev/docs/client/install-kn/ [Knative Broker for Apache Kafka]: https://knative.dev/docs/eventing/brokers/broker-types/kafka-broker/ diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index e6103fa..f37e7b7 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -104,7 +104,7 @@ The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed -into a series of [issues] and entered as GitHub [project-doc-website]/issues. +into a series of issues and entered on GitHub `PROJECT-DOC-WEBSITE/issues`. ### How to use this document @@ -115,9 +115,9 @@ Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: -- [Project documentation](./?TODO=ADD-URL) -- [Contributor documentation](./?TODO=ADD-URL) -- [Website and documentation infrastructure](./?TODO=ADD-URL) +- [Project documentation](#project-documentation) +- [Contributor documentation](#contributor-documentation) +- [Website and documentation infrastructure](#website-and-infrastructure) Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. @@ -550,8 +550,7 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-doc-website]: ./?_PROJECT-DOC-URL_ -[project-website]: ./?_PROJECT-WEBSITE_ +[project-website]: _PROJECT-WEBSITE_ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md diff --git a/docs/index.md b/docs/index.md index 6d837e3..4fca64e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -52,8 +52,8 @@ Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses -- Documentation: [CC-BY-4.0](LICENSE) -- Code: [Apache-2.0](LICENSE-CODE) +- Documentation: [CC-BY-4.0](https://github.com/cncf/techdocs/blob/main/LICENSE) +- Code: [Apache-2.0](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE) [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours diff --git a/docs/repo-setup.md b/docs/repo-setup.md index bf7003c..670bc10 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -39,10 +39,11 @@ For documentation this means you must: ```markdown # License - $PROJECT_NAME is licensed under an [Apache 2.0 license](./LICENSE). + $PROJECT_NAME is licensed under an + [Apache 2.0 license](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE). The #PROJECT_NAME documentation is licensed under a - [CC-BY-4.0 license](./LICENSE-docs). + [CC-BY-4.0 license](https://github.com/cncf/techdocs/blob/main/LICENSE). ``` 2. Add both the CC-BY-4.0 `LICENSE-docs` and Apache 2.0 `LICENSE` files to the diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index f4ba814..9c7d425 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -5,7 +5,7 @@ title: Website guidelines & checklist # Website guidelines & checklist Per the -[CNCF Website Guidelines](https://github.com/cncf/foundation/blob/main/website-guidelines.md), +[CNCF Website Guidelines](https://github.com/cncf/foundation/blob/main/policies-guidance/website-guidelines.md), the following should be present:
_Note_, not all of these are applicable to all projects From 785d20866ab9f401ee6ae99f7d924b9cc56a01f3 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 00:24:06 -0700 Subject: [PATCH 053/104] Removed incomplete links The source for "Adding Analytics" is no longer available, removed links. Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/analytics/index.md | 2 +- docs/analytics/ua-to-ga4.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/analytics/index.md b/docs/analytics/index.md index 05a972b..1a59940 100644 --- a/docs/analytics/index.md +++ b/docs/analytics/index.md @@ -13,7 +13,7 @@ title: Analytics Administrator of their existing GA account. - Request the creation of a new analytics property. - For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your - [Docsy][]-based website, see [Adding Analytics][]. + [Docsy][]-based website, see Adding Analytics. > **Archived instructions**: for details on how to migrate from Universal > Analytics to GA4, see diff --git a/docs/analytics/ua-to-ga4.md b/docs/analytics/ua-to-ga4.md index 4ad3736..1b6bbf5 100644 --- a/docs/analytics/ua-to-ga4.md +++ b/docs/analytics/ua-to-ga4.md @@ -164,7 +164,7 @@ code (such as custom Hugo partials) to enable GA4, consider removing the custom code in favor of the native support provided by your site-generator tooling. For example, for [Docsy][]-based websites, all you need to do is provide your -project's GA4 measurement ID. Details are provided in [Adding Analytics][]. Of +project's GA4 measurement ID. Details are provided in Adding Analytics. Of course, this may require you to upgrade the version of [Docsy][] and/or Hugo that your project is using. From 73c6ae7eca146b5d3b6d82a0c70fb371ecdc456c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 00:52:34 -0700 Subject: [PATCH 054/104] Update analysis.md Removed possible formatting build problems Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 45 +++++++++++++++---------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index d7959cf..b41903a 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -16,7 +16,7 @@ According to CNCF best practices guidelines, effective documentation is a prereq ### Purpose -This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, , outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. +This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. This document: @@ -28,17 +28,17 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the Flatcar GitHub repository. -The Flatcar website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the Flatcar GitHub repo. +The Flatcar website and documentation are written in Markdown and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the Flatcar GitHub repo. #### In scope -- Website: -- Documentation: -- Website repo: +- Website: https://www.flatcar.org +- Documentation: https://www.flatcar.org/docs/latest +- Website repo: https://github.com/flatcar/flatcar-website #### Out of scope -Other Flatcar repos: , for any not listed in "In scope". +Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-webite. ### How this document is organized @@ -61,9 +61,9 @@ Readers interested only in actionable improvements should skip this document and Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: -- [Project documentation](./?TODO=ADD-URL) -- [Contributor documentation](./?TODO=ADD-URL) -- [Website and documentation infrastructure](./?TODO=ADD-URL) +- [Project documentation](https://www.flatcar.org/docs/latest) +- [Contributor documentation](https://www.flatcar.org/docs/latest/contribute/) +- [Website and documentation infrastructure](https://github.com/flatcar/flatcar-website) Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. @@ -404,9 +404,9 @@ Listed here are the minimal website requirements for projects based on their [ma -[git-submodules]: [maturity-level]: - -[cncf-servicedesk]: +git-submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules +maturity-level: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +cncf-servicedesk: https://servicedesk.cncf.io #### Usability, accessibility and devices @@ -418,8 +418,7 @@ Most CNCF websites are accessed from mobile and other non-desktop devices at lea site search and in-page table of contents?** - **Might a [mobile-first] design make sense for your project?** -[mobile-first]: - https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first +[mobile-first](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) Plan for suitable [accessibility][] measures for your website. For example: @@ -429,7 +428,7 @@ Plan for suitable [accessibility][] measures for your website. For example: It is up to each project to set their own guidelines. -[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility +[accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) #### Branding and design @@ -520,11 +519,11 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -[criteria]: ../criteria.md -[implementation]: ./implementation.md -[issues list]: ./issues-list.md -[project-doc-website]: ./?https://www.flatcar.org/docs/latest -[project-website]: ./?https://www.flatcar.org/ -[Rating (1-5)]: #rating-values -[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 -[website guidelines]: ../../website-guidelines-checklist.md +criteria ./criteria.md +implementation ./implementation.md +issues list ./issues-list.md +project-doc-website ./?https://www.flatcar.org/docs/latest +project-website https://www.flatcar.org/ +Rating (1-5) rating-values +rfc-spec https://www.rfc-editor.org/rfc/rfc2119 +website guidelines ../../website-guidelines-checklist.md From ab95cae523e34589b74f13dc0f777177b3ddafb3 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 07:17:26 -0700 Subject: [PATCH 055/104] Update analysis.md Formatting Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 59 +++++++++++++++---------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index b41903a..2b49c10 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,13 +10,13 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analysis the effectiveness and completeness of the [Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. +This document is an analysis the effectiveness and completeness of the [Flatcar](https://www.flatcar.org/docs/latest) open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. ### Purpose -This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. +This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second **implementation** document, outlines an actionable plan for improvement. A third document is an **issues list** of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. This document: @@ -28,7 +28,7 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the Flatcar GitHub repository. -The Flatcar website and documentation are written in Markdown and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the Flatcar GitHub repo. +The Flatcar website and documentation are written in Markdown and are compiled using the "static site" generator with the "theme" and served from "platform". The site's code is stored on the Flatcar GitHub repo. #### In scope @@ -48,16 +48,16 @@ This document is divided into three sections that represent three major areas of - **Contributor documentation:** concerns documentation for new and existing contributors to the Flatcar OSS project - **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability -Each section begins with summary ratings based on a rubric with appropriate [criteria] for the section, then proceeds to: +Each section begins with summary ratings based on a rubric with appropriate criteria for the section, then proceeds to: - **Comments**: observations about the existing documentation, with a focus on how it does or does not help Flatcar users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. -The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of [issues] and entered as GitHub [project-doc-website]/issues. +The accompanying implementation document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of issues and entered as GitHub project-doc-website/issues. ### How to use this document -Readers interested only in actionable improvements should skip this document and read the **[implementation] plan** and **[issues] list**. +Readers interested only in actionable improvements should skip this document and read the **implementation plan** and **issues list**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: @@ -69,7 +69,7 @@ Examples of CNCF documentation that demonstrate the analysis criteria are linked #### Recommendations, requirements, and best practices -This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-spec], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. +This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of RFCs, the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. ## Project documentation @@ -103,7 +103,7 @@ The "Learning Series" node, introduced into the documentation recently, outlines - The systemd is about core OS management. - The "Container Runtimes" node is an expected node focused on containers and clusters. An argument could be made to elevate "Getting Started with Kubernetes" and "High Availability Kubernetes" to its own node, as Flatcar has its optimization benefits for Kubernetes deployment. - The "Migrating from CoreOS" node might be better placed earlier or within an Installation node, as it is an installation scenario. -- The "Reference" node contains expected look-up information such as "Constance and IDs" and "Supply chain security mechanisms" but these sections could have better placement: +- The "Reference" node contains expected look-up information such as "Constance and IDs" and "Supply chain security mechanisms" but these sections could have better placement: - "Integrations" could be incorporated into the Cloud Providers documentation. - "Developer Guides" contains conceptual content typically not found in a Reference section, so "Developer Guides" or something more descriptive like "Flatcar Development Guides" should be a top-tier node. - The "How to Contribute" node is well-placed has the expected content. @@ -296,9 +296,9 @@ One of the easiest ways to attract new contributors is making sure they know how We evaluate on the following: -- **Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?** +- **Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?** - **Is there a direct link to your GitHub organization/repository?** -- **Are weekly/monthly project meetings documented?** Is it clear how someone can join those meetings?** +- **Are weekly/monthly project meetings documented?** Is it clear how someone can join those meetings?** - **Are mailing lists documented?** #### Beginner friendly issue backlog @@ -306,7 +306,7 @@ We evaluate on the following: We evaluate on the following: - **Are docs issues well-triaged?** -- **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** +- **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** - **Are issues well-documented (i.e., more than just a title)?** - **Are issues maintained for staleness?** @@ -344,11 +344,11 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. +Flatcar is a **graduated** project of CNCF. This means that the project should have high criteria standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ------------------------------------------- | -------------- | @@ -384,7 +384,7 @@ Source files for _all website pages_ should reside in a single repo. Among other - **increases the likelihood of errors - **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][git-submodules]. +Ideally, all website files should be in the **website repo** itself. Alternatively, files should be brought into the website repo via git 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. @@ -397,20 +397,23 @@ Listed here are the minimal website requirements for projects based on their [ma | Criterion | Incubating Requirement | Graduated Requirement | | ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | | [Website guidelines] | All guidelines satisfied | All guidelines satisfied | -| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Docs analysis** (this) | Requested through CNCF service desk | All follow-up actions addressed | | **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | -| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: hosting | Hosted directly | | **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | -git-submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules -maturity-level: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations -cncf-servicedesk: https://servicedesk.cncf.io +[git-submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) +[maturity-level](https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations) +[cncf-servicedesk](https://servicedesk.cncf.io) #### Usability, accessibility and devices -Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. +Most CNCF websites are accessed from mobile and other non-desktop devices. + at least 10-20% of the time. +Planning for this early in your website's design will be much less effort than +retrofitting a desktop-first design. - **Is the website usable from mobile?** - **Are doc pages readable?** @@ -454,7 +457,9 @@ We evaluate on the following: #### 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 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. We evaluate on the following: @@ -476,7 +481,8 @@ Website maintenance is an important part of project success, especially when pro We evaluate on the following: -- **Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?**) +- **Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) +- or commonly used by CNCF projects (our recommended tech stack?**) - **Are you actively cultivating website maintainers from within the community?** - **Are site build times reasonable?** - **Do site maintainers have adequate permissions?** @@ -519,11 +525,4 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -criteria ./criteria.md -implementation ./implementation.md -issues list ./issues-list.md -project-doc-website ./?https://www.flatcar.org/docs/latest -project-website https://www.flatcar.org/ -Rating (1-5) rating-values -rfc-spec https://www.rfc-editor.org/rfc/rfc2119 -website guidelines ../../website-guidelines-checklist.md + From 38355bb2bbdd659961da607278bde4449d238022 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 07:28:23 -0700 Subject: [PATCH 056/104] Update analysis.md Formatting Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 32 +++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 2b49c10..bede3d5 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -390,7 +390,7 @@ If a project chooses to keep source files in multiple repos, they need a clearly #### Minimal website requirements -Listed here are the minimal website requirements for projects based on their [maturity level][maturity-level], either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) +Listed here are the minimal website requirements for projects based on their maturity level, either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) @@ -406,24 +406,24 @@ Listed here are the minimal website requirements for projects based on their [ma [git-submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) [maturity-level](https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations) -[cncf-servicedesk](https://servicedesk.cncf.io) +[service desk](https://servicedesk.cncf.io) #### Usability, accessibility and devices Most CNCF websites are accessed from mobile and other non-desktop devices. - at least 10-20% of the time. -Planning for this early in your website's design will be much less effort than +At least 10-20% of the time. +Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. - **Is the website usable from mobile?** - **Are doc pages readable?** - **Are all / most website features accessible from mobile -- **such as the top-nav, - site search and in-page table of contents?** +site search and in-page table of contents?** - **Might a [mobile-first] design make sense for your project?** [mobile-first](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) -Plan for suitable [accessibility][] measures for your website. For example: +Plan for suitable accessibility measures for your website. For example: - **Are color contrasts significant enough for color-impaired readers?** - **Are most website features usable using a keyboard only?** @@ -431,25 +431,26 @@ Plan for suitable [accessibility][] measures for your website. For example: It is up to each project to set their own guidelines. -[accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) +[Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) #### Branding and design -CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing. +CNCF seeks to support enterprise-ready open source software. We evaluate on the following: -- **Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable?** +- **Is there an easily recognizable brand for the project (logo + color scheme) - **Is the brand used across the website consistently?** - **Is the website’s typography clean and well-suited for reading?** #### Case studies/social proof -One of the best ways to advertise an open source project is to show other organizations using it. +One of the best ways to advertise an open source project is to show other organizations. + We evaluate on the following: -- **Are there case studies available for the project and are they documented on the website?** +- **Are there case studies available for the project and are they documented. - **Are there user testimonials available?** - **Is there an active project blog?** - **Are there community talks for the project and are they present on the website?** @@ -477,12 +478,13 @@ We evaluate on the following: #### Maintenance planning -Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. +Website maintenance is an important part of project success, especially +maintainers aren’t web developers. We evaluate on the following: -- **Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) -- or commonly used by CNCF projects (our recommended tech stack?**) +- **Is your website tooling well-supported by the community. +- Commonly used by CNCF projects (our recommended tech stack?**) - **Are you actively cultivating website maintainers from within the community?** - **Are site build times reasonable?** - **Do site maintainers have adequate permissions?** @@ -524,5 +526,3 @@ The numeric rating values used in this document are as follows 3. Meets standards 4. Meets or exceeds standards 5. Exemplary - - From 31ce535e67177461f720642e99eaca60de620c79 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 07:35:45 -0700 Subject: [PATCH 057/104] Update analysis.md Temporarily removed last sections to isolate formatting issue Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 262 ------------------------------ 1 file changed, 262 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index bede3d5..6c09d9f 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -264,265 +264,3 @@ No, the complexity of the content is a given, and the content assumes a level of #### Content creation processes #### Inclusive language - -## Contributor documentation - -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. - -| Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | -| Communication methods documented | [rating (1-5)] | -| Beginner friendly issue backlog | [rating (1-5)] | -| “New contributor” getting started content | [rating (1-5)] | -| Project governance documentation | [rating (1-5)] | - -### Comments - -> AUTHOR NOTE: make any overall comments about the Contributor Documentation > here. - -The following sections contain brief assessments of each element of the Contributor Documentation rubric. - -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet > these criteria. Keep in mind that much of the contributor documentation might > be contained in the documentation repository. (Criteria are copied from > criteria.md) - -#### Communication methods documented - -One of the easiest ways to attract new contributors is making sure they know how to reach you. - -We evaluate on the following: - -- **Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?** -- **Is there a direct link to your GitHub organization/repository?** -- **Are weekly/monthly project meetings documented?** Is it clear how someone can join those meetings?** -- **Are mailing lists documented?** - -#### Beginner friendly issue backlog - -We evaluate on the following: - -- **Are docs issues well-triaged?** -- **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** -- **Are issues well-documented (i.e., more than just a title)?** -- **Are issues maintained for staleness?** - -#### New contributor getting started content - -Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily?** - -We evaluate on the following: - -- **Do you have a community repository or section on your website?** -- **Is there a document specifically for new contributors/your first contribution?** -- **Do new users know where to get help?** - -#### Project governance documentation - -One of the CNCF’s core project values is open governance. - -We evaluate on the following: - -- **Is project governance clearly documented?** - -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. - -#### Communication methods documented - -#### Beginner friendly issue backlog - -#### New contributor getting started content - -#### Project governance documentation - -## Website and infrastructure - -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -Flatcar is a **graduated** project of CNCF. This means that the project should have high criteria standards for documentation. - -> AUTHOR NOTE: or - -Flatcar is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. - -| Criterion | [Rating (1-5)] | -| ------------------------------------------- | -------------- | -| Single-source for all files | [rating (1-5)] | -| Meets min website req. (for maturity level) | [rating (1-5)] | -| Usability, accessibility, and design | [rating (1-5)] | -| Branding and design | [rating (1-5)] | -| Case studies/social proof | [rating (1-5)] | -| SEO, Analytics, and site-local search | [rating (1-5)] | -| Maintenance planning | [rating (1-5)] | -| A11y plan & implementation | [rating (1-5)] | -| Mobile-first plan & impl. | [rating (1-5)] | -| HTTPS access & HTTP redirect | [rating (1-5)] | -| Google Analytics 4 for production only | [rating (1-5)] | -| Indexing allowed for production server only | [rating (1-5)] | -| Intra-site / local search | [rating (1-5)] | -| Account custodians are documented | [rating (1-5)] | - -### Comments - -> AUTHOR NOTE: make any overall comments about the Website and documentation > infrastructure here. - -The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. - -> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet > these criteria. Keep in mind that much of the website infrastructure criteria > depend on the tools (static site generator, website framework and hosting, > analytics tools, etc.) and processes (project CI, release procedures, > governance, etc.) used to produce the documentation. (Criteria are copied from > criteria.md) - -#### Single-source requirement - -Source files for _all website pages_ should reside in a single repo. Among other problems, keeping source files in two places: - -- **confuses contributors -- **requires you to keep two sources in sync -- **increases the likelihood of errors -- **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. - -If a project chooses to keep source files in multiple repos, they need a clearly documented strategy for managing mirrored files and new contributions. - -#### Minimal website requirements - -Listed here are the minimal website requirements for projects based on their maturity level, either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) - - - -| Criterion | Incubating Requirement | Graduated Requirement | -| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | -| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | -| **Docs analysis** (this) | Requested through CNCF service desk | All follow-up actions addressed | -| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | -| **Project doc**: hosting | Hosted directly | -| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | - - - -[git-submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) -[maturity-level](https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations) -[service desk](https://servicedesk.cncf.io) - -#### Usability, accessibility and devices - -Most CNCF websites are accessed from mobile and other non-desktop devices. -At least 10-20% of the time. -Planning for this early in your website's design will be much less effort than -retrofitting a desktop-first design. - -- **Is the website usable from mobile?** -- **Are doc pages readable?** -- **Are all / most website features accessible from mobile -- **such as the top-nav, -site search and in-page table of contents?** -- **Might a [mobile-first] design make sense for your project?** - -[mobile-first](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) - -Plan for suitable accessibility measures for your website. For example: - -- **Are color contrasts significant enough for color-impaired readers?** -- **Are most website features usable using a keyboard only?** -- **Does text-to-speech offer listeners a good experience?** - -It is up to each project to set their own guidelines. - -[Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) - -#### Branding and design - -CNCF seeks to support enterprise-ready open source software. - -We evaluate on the following: - -- **Is there an easily recognizable brand for the project (logo + color scheme) -- **Is the brand used across the website consistently?** -- **Is the website’s typography clean and well-suited for reading?** - -#### Case studies/social proof - -One of the best ways to advertise an open source project is to show other organizations. - - -We evaluate on the following: - -- **Are there case studies available for the project and are they documented. -- **Are there user testimonials available?** -- **Is there an active project blog?** -- **Are there community talks for the project and are they present on the website?** -- **Is there a logo wall of users/participating organizations?** - -#### 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. - -We evaluate on the following: - -- **Analytics: - - **Is analytics enabled for the production server?** - - **Is analytics disabled for all other deploys?** - - **If your project used Google Analytics, have you migrated to GA4?** - - **Can Page-not-found (404) reports easily be generated from you site - analytics?** Provide a sample of the site's current top-10 404s. -- **Is site indexing supported for the production server, while disabled for - website previews and builds for non-default branches?** -- **Is local intra-site search available from the website?** -- **Are the current custodian(s) of the following accounts clearly documented: - analytics, Google Search Console, site-search (such as Google CSE or Algolia) - -#### Maintenance planning - -Website maintenance is an important part of project success, especially -maintainers aren’t web developers. - -We evaluate on the following: - -- **Is your website tooling well-supported by the community. -- Commonly used by CNCF projects (our recommended tech stack?**) -- **Are you actively cultivating website maintainers from within the community?** -- **Are site build times reasonable?** -- **Do site maintainers have adequate permissions?** - -#### Other - -- **Is your website accessible via HTTPS?** -- **Does HTTP access, if any, redirect to HTTPS?** - -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - -#### Single-source requirement - -#### Minimal website requirements - -#### Usability, accessibility and devices - -#### Branding and design - -#### Case studies/social proof - -#### SEO, Analytics and site-local search - -#### Maintenance planning - -#### Other - -#### References and notes - -##### Rating values - -The numeric rating values used in this document are as follows - -1. Not present -2. Needs improvement -3. Meets standards -4. Meets or exceeds standards -5. Exemplary From 0e2fb9177c122e70d9211bc4609e00529e039a31 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 07:56:04 -0700 Subject: [PATCH 058/104] Update analysis.md More formatting tests Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 6c09d9f..d69fa09 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -38,7 +38,7 @@ The Flatcar website and documentation are written in Markdown and are compiled u #### Out of scope -Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-webite. +Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-website. ### How this document is organized @@ -253,8 +253,6 @@ No, the complexity of the content is a given, and the content assumes a level of ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. - #### Information architecture #### New user content From cbd320eddf44727a3f70759df82494de2bfa2a96 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 3 Mar 2026 15:48:12 +0000 Subject: [PATCH 059/104] chore: move info from top level README to docs readme Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index 4fca64e..88b8685 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,16 +8,15 @@ sidebar_position: 1 This site contains resources provided by the CNCF Technical Documentation team, including: -- Docs about building websites and developing technical documentation, including - recommended tools, best practices, how-tos, and evaluation checklists. It - provides specific guidelines for: +- Docs about building websites and developing technical documentation, + including recommended tools, best practices, how-tos, and evaluation + checklists. It provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - - Analyzing project documentation. - -It also contains a collection of documentation analyses of CNCF projects -performed by the TechDocs team. + - [Analyzing project documentation](./analysis). +- [Analyses](./analyses): a collection of documentation analyses of CNCF projects + performed by the TechDocs team. ## TechDocs Q&A @@ -45,15 +44,15 @@ The full-time staff of the team is: experience, CNCF - [Nate W.](https://github.com/nate-double-u) - Head of mentoring & documentation, CNCF -- [Patrice Chalin](https://github.com/chalin) - Senior TechDocs & webdev lead +- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead - [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses -- Documentation: [CC-BY-4.0](https://github.com/cncf/techdocs/blob/main/LICENSE) -- Code: [Apache-2.0](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE) +- Documentation: [CC-BY-4.0](LICENSE) +- Code: [Apache-2.0](LICENSE-CODE) [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours From 5efc2a021c5986cefabdc8f98728a75a9fd06e1b Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 3 Mar 2026 15:59:43 +0000 Subject: [PATCH 060/104] chore: fix CI errors Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/index.md b/docs/index.md index 88b8685..abda93f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,15 +8,15 @@ sidebar_position: 1 This site contains resources provided by the CNCF Technical Documentation team, including: -- Docs about building websites and developing technical documentation, - including recommended tools, best practices, how-tos, and evaluation - checklists. It provides specific guidelines for: +- Docs about building websites and developing technical documentation, including + recommended tools, best practices, how-tos, and evaluation checklists. It + provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](./analysis). -- [Analyses](./analyses): a collection of documentation analyses of CNCF projects - performed by the TechDocs team. +- [Analyses](./analyses): a collection of documentation analyses of CNCF + projects performed by the TechDocs team. ## TechDocs Q&A @@ -44,7 +44,7 @@ The full-time staff of the team is: experience, CNCF - [Nate W.](https://github.com/nate-double-u) - Head of mentoring & documentation, CNCF -- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead +- [Patrice Chalin](https://github.com/chalin) - Senior TechDocs & webdev lead - [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate Consultants and volunteers also contribute to CNCF TechDocs efforts. From 5975c0305ede963e75210335696d83ac477d7407 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Thu, 5 Mar 2026 11:25:28 +0000 Subject: [PATCH 061/104] chore: nit fix Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index abda93f..7668554 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,8 +15,9 @@ including: - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](./analysis). -- [Analyses](./analyses): a collection of documentation analyses of CNCF - projects performed by the TechDocs team. + +It also contains a collection of documentation analyses of CNCF projects +performed by the TechDocs team. ## TechDocs Q&A From b243f48ce105ead75237370caad1c9e9d9246023 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 10 Mar 2026 15:34:32 +0000 Subject: [PATCH 062/104] chore: nit fix Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 7668554..6d837e3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,7 +14,7 @@ including: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - - [Analyzing project documentation](./analysis). + - Analyzing project documentation. It also contains a collection of documentation analyses of CNCF projects performed by the TechDocs team. From 5d0674ff5f9e0e7ceffad29df53734545c0656e6 Mon Sep 17 00:00:00 2001 From: Uchechukwu Obasi Date: Tue, 17 Mar 2026 23:06:03 +0000 Subject: [PATCH 063/104] Chore: Fix all broken links outlined in issue description (#345) * Chore: Fix all broken links outlined in issue description Signed-off-by: thisisobate * chore: format files Signed-off-by: thisisobate * chore: fix markdown error Signed-off-by: thisisobate * chore: fix markdown error Signed-off-by: thisisobate * chore: fix markdown error again Signed-off-by: thisisobate * chore: fix link checker in CI Signed-off-by: thisisobate * chore: add backsticks to link Signed-off-by: thisisobate --------- Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6d837e3..4fca64e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -52,8 +52,8 @@ Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses -- Documentation: [CC-BY-4.0](LICENSE) -- Code: [Apache-2.0](LICENSE-CODE) +- Documentation: [CC-BY-4.0](https://github.com/cncf/techdocs/blob/main/LICENSE) +- Code: [Apache-2.0](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE) [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours From d10e962e508d60bc944f21681a65470603f8be65 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 09:13:57 -0700 Subject: [PATCH 064/104] misc edits Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index d69fa09..3b6d599 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -163,7 +163,7 @@ The current content is comprehensive on the key concepts needed for understandin - **If the product exposes an API, is there a complete reference?** - There is a Developer Guide for building Flatcar Container Linux from source and/or in modifying the OS. The SDK is a containerized Software Development Kit that enables developers to customize and build their own Flatcar Container Linux OS images. + There is a Developer Guide for building Flatcar Container Linux from source and/or in modifying the OS. The SDK is a containerized Software Development Kit that enables developers to customize and build their own Flatcar Container Linux OS images. The SDK is not an API with function calls, but rather a kit of scripts and tools. From 9c965cfc0d0bf85eb3aebd7628e9088603a57f95 Mon Sep 17 00:00:00 2001 From: Nate W Date: Fri, 6 Feb 2026 13:52:19 -0800 Subject: [PATCH 065/104] adding ops/servicedesk label (#336) Signed-off-by: Nate W Signed-off-by: Bruce Hamilton --- .github/settings.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/settings.yml b/.github/settings.yml index 6c575c0..62a1acf 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -125,3 +125,4 @@ labels: - name: CNCF Service Desk description: This issue has a related CNCF Service Desk ticket color: 0CD9EF + From e8953d5aa1f6221985b51603d9b064bcd8b7e636 Mon Sep 17 00:00:00 2001 From: Uchechukwu Obasi Date: Sat, 21 Feb 2026 01:42:01 +0300 Subject: [PATCH 066/104] Chore: Drop numbered analysis folders and adopt a date format instead (#337) * chore: drop numbered analysis folders and adopt a date format instead Signed-off-by: thisisobate * chore: prettify docs Signed-off-by: thisisobate * chore: update check-md script Signed-off-by: thisisobate * chore: nit fix Signed-off-by: thisisobate --------- Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- .github/settings.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/settings.yml b/.github/settings.yml index 62a1acf..6c575c0 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -125,4 +125,3 @@ labels: - name: CNCF Service Desk description: This issue has a related CNCF Service Desk ticket color: 0CD9EF - From c96132e0622a9a9656d11b0972738594d1722bf3 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Thu, 26 Feb 2026 21:37:41 -0800 Subject: [PATCH 067/104] Update analysis.md Added template and started customizing Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> --- docs/analysis/templates/analysis.md | 71 +++++++++++------------------ 1 file changed, 26 insertions(+), 45 deletions(-) diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index f37e7b7..e4a20ae 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -1,37 +1,17 @@ --- -title: _PROJECT_ Documentation Analysis -tags: [_PROJECT_] -created: YYYY-MM-DD -modified: YYYY-MM-DD -author: _NAME_ (@_HANDLE_) +title: Flatcar Documentation Analysis +tags: [Flatcar] +created: 2026-02-26 +modified: 2026-02-26 +author: Bruce Hamilton (@iRaindrop) --- -## About this template - -TO USE THIS TEMPLATE, search and replace the named IDs: - -- `_PROJECT_`: project name -- `YYYY-MM-DD`: creation and modification dates of the analysis document -- `_NAME_`: name of the analysis author -- `@_HANDLE_`: GitHub handle of the analysis author -- `_PROJECT-WEBSITE_`: landing page of the project's information website -- `_PROJECT-DOC-URL_`: main page of the technical documentation for the current - project revision; this might be on the main website server, for example as - _PROJECT-WEBSITE_/doc -- `_PROJECT-DOC-REPO_`: repository where the project technical documentation is - stored; this might be its own repo or a directory in the project main repo - -For the analysis procedure, see [Analysis how-to](../howto.md). - -> Note: delete this "About this template" section after you have customized this -> template for a specific project. - ## Introduction This document is an analyzes the effectiveness and completeness of the -[_PROJECT_][project-website] open source software (OSS) project's documentation +[Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. @@ -42,7 +22,7 @@ efforts. ### Purpose -This document was written to analyze the current state of _PROJECT_ +This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, , outlines an actionable plan for improvement. A @@ -52,7 +32,7 @@ improve the documentation. This document: -- Analyzes the current _PROJECT_ technical documentation and website +- Analyzes the current Flatcar technical documentation and website - Compares existing documentation against the CNCF’s standards - Recommends a program of key improvements with the largest return on investment @@ -60,24 +40,24 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the -_PROJECT_ GitHub repository. +Flatcar GitHub repository. -The _PROJECT_ website and documentation are written in [Markdown, ReStructured +The Flatcar website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify -platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. +platform, other]. The site's code is stored on the Flatcar GitHub repo. #### In scope -- Website: _PROJECT-WEBSITE_ -- Documentation: _PROJECT-DOC-URL_ -- Website repo: _PROJECT-DOC-REPO_ +- Website: https://www.flatcar.org/ +- Documentation: https://www.flatcar.org/docs/latest +- Website repo: https://github.com/cncf/techdocs - _[Other; might include a demo server, governance site, or other relevant repositories]_ #### Out of scope -- Other _PROJECT_ repos: _[In general, do not include sub-projects or related +- Other Flatcar repos: _[In general, do not include sub-projects or related "ecosystem" projects]_ ### How this document is organized @@ -85,10 +65,10 @@ platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. This document is divided into three sections that represent three major areas of concern: -- **Project documentation:** concerns documentation for users of the _PROJECT_ +- **Project documentation:** concerns documentation for users of the Flatcar software, aimed at people who intend to use the project software - **Contributor documentation:** concerns documentation for new and existing - contributors to the _PROJECT_ OSS project + contributors to the Flatcar OSS project - **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability @@ -96,7 +76,7 @@ Each section begins with summary ratings based on a rubric with appropriate [criteria] for the section, then proceeds to: - **Comments**: observations about the existing documentation, with a focus on - how it does or does not help _PROJECT_ users achieve their goals. + how it does or does not help Flatcar users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. @@ -138,12 +118,12 @@ to legal requirements such as copyright and licensing issues. > AUTHOR NOTE: Pick the CNCF maturity level of the project: -_PROJECT_ is a **graduated** project of CNCF. This means that the project should +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -_PROJECT_ is an **incubating** project of CNCF. This means that the project +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -254,12 +234,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -_PROJECT_ is a **graduated** project of CNCF. This means that the project should +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -_PROJECT_ is an **incubating** project of CNCF. This means that the project +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -344,12 +324,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -_PROJECT_ is a **graduated** project of CNCF. This means that the project should +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -_PROJECT_ is an **incubating** project of CNCF. This means that the project +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -550,7 +530,8 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-website]: _PROJECT-WEBSITE_ +[project-doc-website]: ./?https://www.flatcar.org/docs/latest +[project-website]: ./?https://www.flatcar.org/ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md From 656295e42e200609384e046ca5e34012669f1bc8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Fri, 27 Feb 2026 20:43:20 -0800 Subject: [PATCH 068/104] File fix - added analysis.md Also restored mistakenly used template Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 18 ++++++-- docs/analysis/templates/analysis.md | 72 ++++++++++++++++++----------- 2 files changed, 61 insertions(+), 29 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 3b6d599..ca25b77 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,13 +10,25 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analysis the effectiveness and completeness of the [Flatcar](https://www.flatcar.org/docs/latest) open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. +This document is an analyzes the effectiveness and completeness of the +[Flatcar][project-website] open source software (OSS) project's documentation +and website. It is funded by the CNCF Foundation as part of its overall effort +to incubate, grow, and graduate open source cloud native software projects. -According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. +According to CNCF best practices guidelines, effective documentation is a +prerequisite for program graduation. The documentation analysis is the first +step of a CNCF process aimed at assisting projects with their documentation +efforts. ### Purpose -This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second **implementation** document, outlines an actionable plan for improvement. A third document is an **issues list** of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. +This document was written to analyze the current state of Flatcar +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second +[implementation] document, , outlines an actionable plan for improvement. A +third document is an [issues list] of issues to be added to the project +documentation repository. These issues can be taken up by contributors to +improve the documentation. This document: diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index e4a20ae..cf539c2 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -1,17 +1,37 @@ --- -title: Flatcar Documentation Analysis -tags: [Flatcar] -created: 2026-02-26 -modified: 2026-02-26 -author: Bruce Hamilton (@iRaindrop) +title: _PROJECT_ Documentation Analysis +tags: [_PROJECT_] +created: YYYY-MM-DD +modified: YYYY-MM-DD +author: _NAME_ (@_HANDLE_) --- +## About this template + +TO USE THIS TEMPLATE, search and replace the named IDs: + +- `_PROJECT_`: project name +- `YYYY-MM-DD`: creation and modification dates of the analysis document +- `_NAME_`: name of the analysis author +- `@_HANDLE_`: GitHub handle of the analysis author +- `_PROJECT-WEBSITE_`: landing page of the project's information website +- `_PROJECT-DOC-URL_`: main page of the technical documentation for the current + project revision; this might be on the main website server, for example as + _PROJECT-WEBSITE_/doc +- `_PROJECT-DOC-REPO_`: repository where the project technical documentation is + stored; this might be its own repo or a directory in the project main repo + +For the analysis procedure, see [Analysis how-to](../howto.md). + +> Note: delete this "About this template" section after you have customized this +> template for a specific project. + ## Introduction This document is an analyzes the effectiveness and completeness of the -[Flatcar][project-website] open source software (OSS) project's documentation +[_PROJECT_][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. @@ -22,7 +42,7 @@ efforts. ### Purpose -This document was written to analyze the current state of Flatcar +This document was written to analyze the current state of _PROJECT_ documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, , outlines an actionable plan for improvement. A @@ -32,7 +52,7 @@ improve the documentation. This document: -- Analyzes the current Flatcar technical documentation and website +- Analyzes the current _PROJECT_ technical documentation and website - Compares existing documentation against the CNCF’s standards - Recommends a program of key improvements with the largest return on investment @@ -40,24 +60,24 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the -Flatcar GitHub repository. +_PROJECT_ GitHub repository. -The Flatcar website and documentation are written in [Markdown, ReStructured +The _PROJECT_ website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify -platform, other]. The site's code is stored on the Flatcar GitHub repo. +platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. #### In scope -- Website: https://www.flatcar.org/ -- Documentation: https://www.flatcar.org/docs/latest -- Website repo: https://github.com/cncf/techdocs +- Website: _PROJECT-WEBSITE_ +- Documentation: _PROJECT-DOC-URL_ +- Website repo: _PROJECT-DOC-REPO_ - _[Other; might include a demo server, governance site, or other relevant repositories]_ #### Out of scope -- Other Flatcar repos: _[In general, do not include sub-projects or related +- Other _PROJECT_ repos: _[In general, do not include sub-projects or related "ecosystem" projects]_ ### How this document is organized @@ -65,10 +85,10 @@ platform, other]. The site's code is stored on the Flatcar GitHub repo. This document is divided into three sections that represent three major areas of concern: -- **Project documentation:** concerns documentation for users of the Flatcar +- **Project documentation:** concerns documentation for users of the _PROJECT_ software, aimed at people who intend to use the project software - **Contributor documentation:** concerns documentation for new and existing - contributors to the Flatcar OSS project + contributors to the _PROJECT_ OSS project - **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability @@ -76,7 +96,7 @@ Each section begins with summary ratings based on a rubric with appropriate [criteria] for the section, then proceeds to: - **Comments**: observations about the existing documentation, with a focus on - how it does or does not help Flatcar users achieve their goals. + how it does or does not help _PROJECT_ users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. @@ -118,12 +138,12 @@ to legal requirements such as copyright and licensing issues. > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -234,12 +254,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -324,12 +344,12 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should +_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project +_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. @@ -530,8 +550,8 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-doc-website]: ./?https://www.flatcar.org/docs/latest -[project-website]: ./?https://www.flatcar.org/ +[project-doc-website]: ./?_PROJECT-DOC-URL_ +[project-website]: ./?_PROJECT-WEBSITE_ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md From 4f90918a13beea612239ae78d17c8755a0d681eb Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Fri, 27 Feb 2026 21:49:39 -0800 Subject: [PATCH 069/104] Update analysis.md Formatting fixes Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 408 +++++++++++++++++++++--------- 1 file changed, 289 insertions(+), 119 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index ca25b77..16e72aa 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,25 +10,13 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analyzes the effectiveness and completeness of the -[Flatcar][project-website] open source software (OSS) project's documentation -and website. It is funded by the CNCF Foundation as part of its overall effort -to incubate, grow, and graduate open source cloud native software projects. +This document is an analyzes the effectiveness and completeness of the [Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. -According to CNCF best practices guidelines, effective documentation is a -prerequisite for program graduation. The documentation analysis is the first -step of a CNCF process aimed at assisting projects with their documentation -efforts. +According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. ### Purpose -This document was written to analyze the current state of Flatcar -documentation. It aims to provide project leaders with an informed understanding -of potential problems in current project documentation. A second -[implementation] document, , outlines an actionable plan for improvement. A -third document is an [issues list] of issues to be added to the project -documentation repository. These issues can be taken up by contributors to -improve the documentation. +This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, , outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. This document: @@ -41,6 +29,7 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the Flatcar GitHub repository. The Flatcar website and documentation are written in Markdown and are compiled using the "static site" generator with the "theme" and served from "platform". The site's code is stored on the Flatcar GitHub repo. +The Flatcar website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the Flatcar GitHub repo. #### In scope @@ -51,6 +40,10 @@ The Flatcar website and documentation are written in Markdown and are compiled u #### Out of scope Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-website. +- Website repo: https://github.com/cncf/techdocs + +#### Out of scope + ### How this document is organized @@ -65,11 +58,11 @@ Each section begins with summary ratings based on a rubric with appropriate crit - **Comments**: observations about the existing documentation, with a focus on how it does or does not help Flatcar users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. -The accompanying implementation document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of issues and entered as GitHub project-doc-website/issues. +The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of [issues] and entered as GitHub [project-doc-website]/issues. ### How to use this document -Readers interested only in actionable improvements should skip this document and read the **implementation plan** and **issues list**. +Readers interested only in actionable improvements should skip this document and read the **[implementation] plan** and **[issues] list**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: @@ -81,11 +74,15 @@ Examples of CNCF documentation that demonstrate the analysis criteria are linked #### Recommendations, requirements, and best practices -This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of RFCs, the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. +This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-spec], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. ## Project documentation -Flatcar is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. + > AUTHOR NOTE: or + Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | -------------------------- | -------------- | @@ -101,176 +98,349 @@ The following sections contain brief assessments of each element of the project The current Flatcar documentation table of contents defines the needed areas of knowledge to install and provision Flatcar, but it does not readily show the different paths for new users depending on their environment. -The following comments regard the top-tier nodes in the current table of contents: - -- The top overview page contains headings with short paragraphs and links that provide additional views and categorization of Flatcar topics. These links are not necessarily parallel with the table of contents hierarchy. -- The "Installing" node Overview page introduces the needed guidance for the provisioning and configuration of Flatcar, but it also contains getting started code for a VM installation. That content is better served by a Getting Started node or the Learning Series node. -- The "Installing" node contains the large "Cloud Providers" node, that might be better as top tier node, same with "Bare Metal". The team agrees that "Community supported platforms" could be merged into the Cloud Providers node. The installation node should be primarily addressing all the new user paths, providing an installation roadmap or strategy. -The "Learning Series" node, introduced into the documentation recently, outlines the key steps for installing, configuring, and managing Flatcar conveying the life cycle. It would be good for the top nodes to have a similar flow. -- The "Provisioning Tools" title is descriptive, but its unclear how other areas of the docs relate to this section. -- The "Nebraska" node is about updates, but it should convey the functionality and its location is unusual prominence. -- The "Setup and Operations" node is too much of a wide net in its title. How does "setup" differ from installation? The node contains several important content areas that should be more discoverable, for instance: - - "Managing Clusters" might be better at a higher level because it's an initial evaluation of whether to deploy Flatcar. - - The Storage and Security nodes are typically at a higher level. - - The systemd is about core OS management. -- The "Container Runtimes" node is an expected node focused on containers and clusters. An argument could be made to elevate "Getting Started with Kubernetes" and "High Availability Kubernetes" to its own node, as Flatcar has its optimization benefits for Kubernetes deployment. -- The "Migrating from CoreOS" node might be better placed earlier or within an Installation node, as it is an installation scenario. -- The "Reference" node contains expected look-up information such as "Constance and IDs" and "Supply chain security mechanisms" but these sections could have better placement: - - "Integrations" could be incorporated into the Cloud Providers documentation. - - "Developer Guides" contains conceptual content typically not found in a Reference section, so "Developer Guides" or something more descriptive like "Flatcar Development Guides" should be a top-tier node. -- The "How to Contribute" node is well-placed has the expected content. - -The documentation also includes an FAQ, accessible from the top banner of the home page. It has some content that would be good to verify that its in the main docs, such as historical context and how images are updated. Conversely, there should be a few top-of-mind installation and support FAQ items derived from the docs. - -Code blocks are different from other documentation sets as they are not bordered or have a different fill background, don't have a copy button, and the language is not noted. - -New users might not be sure of the context for a given block of code. Is the Linux prompt in a VM, in a client computer, or in a CLI session with a cloud provider? Normally this can be deduced by the narrative, but starting a procedure with "In the VM window, use the following command to ..." or similar guidance. - -It should be noted that a new proposed structure is proposed by the team, with the top nodes as follows: - - Flatcar Concepts and Quick Start - Configuration and Provisioning - Deploying to Public Cloud, Private Cloud, and Bare Metal - Kubernetes - In-place updates and roll-backs - The Nebraska update server - Customizing and Extending the OS image - Troubleshooting - Developer Guides - Legacy Information - -Essentially all the pertinent areas of knowledge to install and run Flatcar have been identified and documented. Then just need to be better organized. The next step is to structure the documentation so that it meets these objectives: - -- The node and topic titles provide expected guidance, such as "Getting Started", with nodes and sections organized for precise purposes, rather than headings that serve as broad categories such as "Setup and Operations". -- The structure provides the expected flow and orientation of users so that they can identify a pathway for learning about and deploying Flatcar efficiently and optimally. -- The structure provides effective navigation and identification of the tools and technologies so that users efficiently learn about the ones they need to use. +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and > especially the technical documentation, meet these criteria. (Criteria are > copied from criteria.md) #### Information architecture The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: -##### Is there high-level conceptual or About content? +- Is there high level conceptual/“About” content? Is the documentation feature complete? (i.e., each product feature is documented) - Are there step-by-step instructions (tasks, tutorials) documented for features? +- Are there any key features which are documented but missing task documentation? +- Is the “happy path”/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) +- If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) +- If the product exposes an API, is there a complete reference? +- Is content up to date and accurate? The current content is comprehensive on the key concepts needed for understanding the processes and technologies involved. It's just a matter of organizing discussion of the concepts to map to the user the path for installing and configuring Flatcar. -- **Is the documentation feature complete?** +New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: - Yes, given that Flatcar is essentially an operating system and new features and capabilities will be apparent and easily referenced. +- Is “getting started” clearly labeled? (“Getting started”, “Installation”, “First steps”, etc.) +- Is installation documented step-by-step? +- If needed, are multiple OSes documented? +- Do users know where to go after reading the getting started guide? +- Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? +- Is there sample code or other example content that can easily be copy-pasted? - **Are there step-by-step instructions (tasks, tutorials) documented for features?** - Procedures, mainly invoking bash commands, are introduced informally and do not have the typical Microsoft style of numbered steps that read "Use the following command to ..." verbiage. It would be easy to rewrite for meet that conformity. +As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. -- **Are there any key features which are documented but missing task documentation?** +We evaluate on the following: - Not so much regarding features, but there are tasks in using provisioning tools where step-by-step guidance would be appreciated. +- Is your documentation searchable? +- Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? +- Do you have a clearly documented method for versioning your content? -- **Are tasks clearly named according to user goals providing a happy path for users to get their tasks accomplished?** +Yes, the home page has a search bar where any results populate a dropdown for selection. - Not currently. But the needed content areas are established and just need to be coordinated into a "Flatcar installation roadmap" for most paths. +Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. -- **If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ)** +We evaluate on the following: - There is an FAQ that needs updating. +- Is there a clearly documented (ongoing) contribution process for documentation? +- Does your code release process account for documentation creation & updates? +- Who reviews and approves documentation pull requests? +- Does the website have a clear owner/maintainer? -- **If the product exposes an API, is there a complete reference?** +Yes. There is a 'How to contribute' node with guidance for using the GitHub repository, formatting, and style. - There is a Developer Guide for building Flatcar Container Linux from source and/or in modifying the OS. The SDK is a containerized Software Development Kit that enables developers to customize and build their own Flatcar Container Linux OS images. +- **Does your code release process account for documentation creation & updates?** - The SDK is not an API with function calls, but rather a kit of scripts and tools. +Supported, but not a formalized process at this time. -##### New user content +- **Who reviews and approves documentation pull requests?** -New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: +Team members are determined. -- **Is “getting started” or similar clearly labeled?** +- **Does the website have a clear owner/maintainer?** -The "Learning Series" is a well-documented getting started guide. There is a Heading 3 heading "Getting started" in the overview. +Team members are determined. -- **Is installation documented step-by-step?** +##### Inclusive language -Procedures are not formal step-by-steps, but rather sufficient descriptions of the purpose and result of running the provided code example. +Creating inclusive project communities is a key goal for all CNCF projects. -Even if the new user does not know anything about the technologies, it can still be logical and understandable by looking up terms. +We evaluate on the following: -- **If needed, are multiple OSes documented?** +- Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the + [Inclusive Naming Initiative](https://inclusivenaming.org) website? +- Does the project use language like "simple", "easy", etc.? -Users are typically running a Linux machine, or a VM running on Windows or MacOS. It would be beneficial to acquaint the user with any client OS guidance, particularly when installing tools and images. +### Recommendations -- **Do users know where to go after reading the getting started guide?** +> AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. -Intuitively perhaps, as the Learning Services provides sufficient content to get Flatcar instances running. It would be good to have listings of next steps for the various deployment scenarios. +#### Information architecture -- **Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture?** +#### New user content -Other than being a top level node in the table of contents, no. +#### Content maintainability & site mechanics -- **Is there sample code or other example content that can easily be copy-pasted?** +#### Content creation processes -Yes, most pages have code samples, but currently the UI does not show code example blocks with copy buttons. The code is simply in a different font. +#### Inclusive language -##### Content maintainability & site mechanics +## Contributor documentation -As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. + +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | [rating (1-5)] | +| Beginner friendly issue backlog | [rating (1-5)] | +| “New contributor” getting started content | [rating (1-5)] | +| Project governance documentation | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Contributor Documentation > here. + +The following sections contain brief assessments of each element of the Contributor Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet > these criteria. Keep in mind that much of the contributor documentation might > be contained in the documentation repository. (Criteria are copied from > criteria.md) + +#### Communication methods documented + +One of the easiest ways to attract new contributors is making sure they know how to reach you. We evaluate on the following: -- **Is your documentation searchable?** +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? +- Is there a direct link to your GitHub organization/repository? +- Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? +- Are mailing lists documented? -Yes, the home page has a search bar where any results populate a dropdown for selection. +#### Beginner friendly issue backlog + +We evaluate on the following: -- **Are you planning for localization/internationalization?** +- Are docs issues well-triaged? +- Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? +- Are issues well-documented (i.e., more than just a title)? +- Are issues maintained for staleness? -There are currently no plans for localization. +#### New contributor getting started content -- **Do you have a clearly documented method for versioning your content?** +Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily? -Being an incubating project, the content is not versioned at this time. +We evaluate on the following: -##### Content creation processes +- Do you have a community repository or section on your website? +- Is there a document specifically for new contributors/your first contribution? +- Do new users know where to get help? -Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. +#### Project governance documentation + +One of the CNCF’s core project values is open governance. We evaluate on the following: -- **Is there a clearly documented (ongoing) contribution process for documentation?** +- Is project governance clearly documented? -Yes. There is a 'How to contribute' node with guidance for using the GitHub repository, formatting, and style. +### Recommendations -- **Does your code release process account for documentation creation & updates?** +> AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. -Supported, but not a formalized process at this time. +#### Communication methods documented -- **Who reviews and approves documentation pull requests?** +#### Beginner friendly issue backlog -Team members are determined. +#### New contributor getting started content -- **Does the website have a clear owner/maintainer?** +#### Project governance documentation -Team members are determined. +## Website and infrastructure -##### Inclusive language +> AUTHOR NOTE: Pick the CNCF maturity level of the project: -Creating inclusive project communities is a key goal for all CNCF projects. +Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. + +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | [rating (1-5)] | +| Meets min website req. (for maturity level) | [rating (1-5)] | +| Usability, accessibility, and design | [rating (1-5)] | +| Branding and design | [rating (1-5)] | +| Case studies/social proof | [rating (1-5)] | +| SEO, Analytics, and site-local search | [rating (1-5)] | +| Maintenance planning | [rating (1-5)] | +| A11y plan & implementation | [rating (1-5)] | +| Mobile-first plan & impl. | [rating (1-5)] | +| HTTPS access & HTTP redirect | [rating (1-5)] | +| Google Analytics 4 for production only | [rating (1-5)] | +| Indexing allowed for production server only | [rating (1-5)] | +| Intra-site / local search | [rating (1-5)] | +| Account custodians are documented | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Website and documentation > infrastructure here. + +The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. + +> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet > these criteria. Keep in mind that much of the website infrastructure criteria > depend on the tools (static site generator, website framework and hosting, > analytics tools, etc.) and processes (project CI, release procedures, > governance, etc.) used to produce the documentation. (Criteria are copied from > criteria.md) + +#### Single-source requirement + +Source files for _all website pages_ should reside in a single repo. Among other problems, keeping source files in two places: + +- confuses contributors +- requires you to keep two sources in sync +- increases the likelihood of errors +- 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][git-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. + +#### Minimal website requirements + +Listed here are the minimal website requirements for projects based on their [maturity level][maturity-level], either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) + + + +| Criterion | Incubating Requirement | Graduated Requirement | +| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | +| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + + + +[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules [maturity-level]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[cncf-servicedesk]: https://servicedesk.cncf.io + +#### Usability, accessibility and devices + +Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. + +- Is the website usable from mobile? +- Are doc pages readable? +- Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? +- Might a [mobile-first] design make sense for your project? + +[mobile-first]: + https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first + +Plan for suitable [accessibility][] measures for your website. For example: + +- Are color contrasts significant enough for color-impaired readers? +- Are most website features usable using a keyboard only? +- Does text-to-speech offer listeners a good experience? + +It is up to each project to set their own guidelines. + +[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility + +#### Branding and design + +CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing. We evaluate on the following: -- **Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website?** +- 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? -The 175 hits were "master", "disable", "abort", and "man in the middle". Of those only "abort" would necessitate a fix on eight occurrences. +#### Case studies/social proof -- **Does the project use language like "simple", "easy", etc.?** +One of the best ways to advertise an open source project is to show other organizations using it. -No, the complexity of the content is a given, and the content assumes a level of sophistication where such verbiage would be suspicious. +We evaluate on the following: + +- Are there case studies available for the project and are they documented on the website? +- Are there user testimonials available? +- Is there an active project blog? +- Are there community talks for the project and are they present on the website? +- Is there a logo wall of users/participating organizations? + +#### 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. + +We evaluate on the following: + +- Analytics: + - Is analytics enabled for the production server? + - Is analytics disabled for all other deploys? + - If your project used Google Analytics, have you migrated to GA4? + - Can Page-not-found (404) reports easily be generated from you site + analytics? Provide a sample of the site's current top-10 404s. +- Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches? +- Is local intra-site search available from the website? +- Are the current custodian(s) of the following accounts clearly documented: + analytics, Google Search Console, site-search (such as Google CSE or Algolia) + +#### Maintenance planning + +Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. + +We evaluate on the following: + +- Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) +- Are you actively cultivating website maintainers from within the community? +- Are site build times reasonable? +- Do site maintainers have adequate permissions? + +#### Other + +- Is your website accessible via HTTPS? +- Does HTTP access, if any, redirect to HTTPS? ### Recommendations -#### Information architecture +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. -#### New user content +#### Single-source requirement -#### Content maintainability & site mechanics +#### Minimal website requirements -#### Content creation processes +#### Usability, accessibility and devices -#### Inclusive language +#### Branding and design + +#### Case studies/social proof + +#### SEO, Analytics and site-local search + +#### Maintenance planning + +#### Other + +#### References and notes + +##### Rating values + +The numeric rating values used in this document are as follows + +1. Not present +2. Needs improvement +3. Meets standards +4. Meets or exceeds standards +5. Exemplary + +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues-list.md +[project-doc-website]: ./?https://www.flatcar.org/docs/latest +[project-website]: ./?https://www.flatcar.org/ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md From a3031ae59ef2c2f88d91eafc0fea4b8279aafb3b Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Sun, 29 Mar 2026 23:41:35 -0700 Subject: [PATCH 070/104] Update analysis.md Initial write-up of analysis Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 190 +++++++++++++++++------------- 1 file changed, 109 insertions(+), 81 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 16e72aa..93d2fda 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,7 +10,7 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analyzes the effectiveness and completeness of the [Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. +This document is an analysis the effectiveness and completeness of the [Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. @@ -44,6 +44,7 @@ Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-we #### Out of scope +Other Flatcar repos: , for any not listed in "In scope". ### How this document is organized @@ -78,11 +79,7 @@ This analysis measures documentation against CNCF project maturity standards, an ## Project documentation -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. - > AUTHOR NOTE: or - Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | -------------------------- | -------------- | @@ -98,29 +95,61 @@ The following sections contain brief assessments of each element of the project The current Flatcar documentation table of contents defines the needed areas of knowledge to install and provision Flatcar, but it does not readily show the different paths for new users depending on their environment. -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and > especially the technical documentation, meet these criteria. (Criteria are > copied from criteria.md) +The following comments regard the top-tier nodes in the current table of contents: + +- The top overview page contains headings with short paragraphs and links that provide additional views and categorization of Flatcar topics. These links are not necessarily parallel with the table of contents hierarchy. +- The "Installing" node Overview page introduces the needed guidance for the provisioning and configuration of Flatcar, but it also contains getting started code for a VM installation. That content is better served by a Getting Started node or the Learning Series node. +- The "Installing" node contains the large "Cloud Providers" node, that might be better as top tier node, same with "Bare Metal". The team agrees that "Community supported platforms" could be merged into the Cloud Providers node. The installation node should be primarily addressing all the new user paths, providing an installation roadmap or strategy. +The "Learning Series" node, introduced into the documentation recently, outlines the key steps for installing, configuring, and managing Flatcar conveying the life cycle. It would be good for the top nodes to have a similar flow. +- The "Provisioning Tools" title is descriptive, but its unclear how other areas of the docs relate to this section. +- The "Nebraska" node is about updates, but it should convey the functionality and its location is unusual prominence. +- The "Setup and Operations" node is too much of a wide net in its title. How does "setup" differ from installation? The node contains several important content areas that should be more discoverable, for instance: + - "Managing Clusters" might be better at a higher level because it's an initial evaluation of whether to deploy Flatcar. + - The Storage and Security nodes are typically at a higher level. + - The systemd is about core OS management. +- The "Container Runtimes" node is an expected node focused on containers and clusters. An argument could be made to elevate "Getting Started with Kubernetes" and "High Availability Kubernetes" to its own node, as Flatcar has its optimization benefits for Kubernetes deployment. +- The "Migrating from CoreOS" node might be better placed earlier or within an Installation node, as it is an installation scenario. +- The "Reference" node contains expected look-up information such as "Constance and IDs" and "Supply chain security mechanisms" but these sections could have better placement: + - "Integrations" could be incorporated into the Cloud Providers documentation. + - "Developer Guides" contains conceptual content typically not found in a Reference section, so "Developer Guides" or something more descriptive like "Flatcar Development Guides" should be a top-tier node. +- The "How to Contribute" node is well-placed has the expected content. + +The documentation also includes an FAQ, accessible from the top banner of the home page. It has some content that would be good to verify that its in the main docs, such as historical context and how images are updated. Conversely, there should be a few top-of-mind installation and support FAQ items derived from the docs. + +Code blocks are different from other documentation sets as they are not bordered or have a different fill background, don't have a copy button, and the language is not noted. + +New users might not be sure of the context for a given block of code. Is the Linux prompt in a VM, in a client computer, or in a CLI session with a cloud provider? Normally this can be deduced by the narrative, but starting a procedure with "In the VM window, use the following command to ..." or similar guidance. + +It should be noted that a new proposed structure is proposed by the team, with the top nodes as follows: + + Flatcar Concepts and Quick Start + Configuration and Provisioning + Deploying to Public Cloud, Private Cloud, and Bare Metal + Kubernetes + In-place updates and roll-backs + The Nebraska update server + Customizing and Extending the OS image + Troubleshooting + Developer Guides + Legacy Information + +Essentially all the pertinent areas of knowledge to install and run Flatcar have been identified and documented. Then just need to be better organized. The next step is to structure the documentation so that it meets these objectives: + +- The node and topic titles provide expected guidance, such as "Getting Started", with nodes and sections organized for precise purposes, rather than headings that serve as broad categories such as "Setup and Operations". +- The structure provides the expected flow and orientation of users so that they can identify a pathway for learning about and deploying Flatcar efficiently and optimally. +- The structure provides effective navigation and identification of the tools and technologies so that users efficiently learn about the ones they need to use. #### Information architecture The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: -- Is there high level conceptual/“About” content? Is the documentation feature complete? (i.e., each product feature is documented) - Are there step-by-step instructions (tasks, tutorials) documented for features? -- Are there any key features which are documented but missing task documentation? -- Is the “happy path”/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) -- If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) -- If the product exposes an API, is there a complete reference? -- Is content up to date and accurate? +##### Is there high-level conceptual or About content? The current content is comprehensive on the key concepts needed for understanding the processes and technologies involved. It's just a matter of organizing discussion of the concepts to map to the user the path for installing and configuring Flatcar. New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: -- Is “getting started” clearly labeled? (“Getting started”, “Installation”, “First steps”, etc.) -- Is installation documented step-by-step? -- If needed, are multiple OSes documented? -- Do users know where to go after reading the getting started guide? -- Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? -- Is there sample code or other example content that can easily be copy-pasted? +- **Is “getting started” or similar clearly labeled?** - **Are there step-by-step instructions (tasks, tutorials) documented for features?** @@ -128,9 +157,7 @@ As a project scales, concerns like localized (translated) content and versioning We evaluate on the following: -- Is your documentation searchable? -- Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? -- Do you have a clearly documented method for versioning your content? +- **Is your documentation searchable?** Yes, the home page has a search bar where any results populate a dropdown for selection. @@ -138,10 +165,7 @@ Documentation is only as useful as it is accurate and well-maintained, and requi We evaluate on the following: -- Is there a clearly documented (ongoing) contribution process for documentation? -- Does your code release process account for documentation creation & updates? -- Who reviews and approves documentation pull requests? -- Does the website have a clear owner/maintainer? +- **Is there a clearly documented (ongoing) contribution process for documentation?** Yes. There is a 'How to contribute' node with guidance for using the GitHub repository, formatting, and style. @@ -163,9 +187,13 @@ Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: -- Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the - [Inclusive Naming Initiative](https://inclusivenaming.org) website? -- Does the project use language like "simple", "easy", etc.? +- **Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website?** + +The 175 hits were "master", "disable", "abort", and "man in the middle". Of those only "abort" would necessitate a fix on eight occurrences. + +- **Does the project use language like "simple", "easy", etc.?** + +No, the complexity of the content is a given, and the content assumes a level of sophistication where such verbiage would be suspicious. ### Recommendations @@ -212,29 +240,29 @@ One of the easiest ways to attract new contributors is making sure they know how We evaluate on the following: -- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? -- Is there a direct link to your GitHub organization/repository? -- Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? -- Are mailing lists documented? +- **Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?** +- **Is there a direct link to your GitHub organization/repository?** +- **Are weekly/monthly project meetings documented?** Is it clear how someone can join those meetings?** +- **Are mailing lists documented?** #### Beginner friendly issue backlog We evaluate on the following: -- Are docs issues well-triaged? -- Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? -- Are issues well-documented (i.e., more than just a title)? -- Are issues maintained for staleness? +- **Are docs issues well-triaged?** +- **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** +- **Are issues well-documented (i.e., more than just a title)?** +- **Are issues maintained for staleness?** #### New contributor getting started content -Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily? +Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily?** We evaluate on the following: -- Do you have a community repository or section on your website? -- Is there a document specifically for new contributors/your first contribution? -- Do new users know where to get help? +- **Do you have a community repository or section on your website?** +- **Is there a document specifically for new contributors/your first contribution?** +- **Do new users know where to get help?** #### Project governance documentation @@ -242,7 +270,7 @@ One of the CNCF’s core project values is open governance. We evaluate on the following: -- Is project governance clearly documented? +- **Is project governance clearly documented?** ### Recommendations @@ -295,10 +323,10 @@ The following sections contain brief assessments of each element of the Website Source files for _all website pages_ should reside in a single repo. Among other problems, keeping source files in two places: -- confuses contributors -- requires you to keep two sources in sync -- increases the likelihood of errors -- makes it more complicated to generate the documentation from source files +- **confuses contributors +- **requires you to keep two sources in sync +- **increases the likelihood of errors +- **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][git-submodules]. @@ -320,28 +348,28 @@ Listed here are the minimal website requirements for projects based on their [ma -[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules [maturity-level]: - https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations -[cncf-servicedesk]: https://servicedesk.cncf.io +[git-submodules]: [maturity-level]: + +[cncf-servicedesk]: #### Usability, accessibility and devices Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. -- Is the website usable from mobile? -- Are doc pages readable? -- Are all / most website features accessible from mobile -- such as the top-nav, - site search and in-page table of contents? -- Might a [mobile-first] design make sense for your project? +- **Is the website usable from mobile?** +- **Are doc pages readable?** +- **Are all / most website features accessible from mobile -- **such as the top-nav, + site search and in-page table of contents?** +- **Might a [mobile-first] design make sense for your project?** [mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first Plan for suitable [accessibility][] measures for your website. For example: -- Are color contrasts significant enough for color-impaired readers? -- Are most website features usable using a keyboard only? -- Does text-to-speech offer listeners a good experience? +- **Are color contrasts significant enough for color-impaired readers?** +- **Are most website features usable using a keyboard only?** +- **Does text-to-speech offer listeners a good experience?** It is up to each project to set their own guidelines. @@ -353,9 +381,9 @@ CNCF seeks to support enterprise-ready open source software. A key aspect of thi 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 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?** #### Case studies/social proof @@ -363,11 +391,11 @@ One of the best ways to advertise an open source project is to show other organi We evaluate on the following: -- Are there case studies available for the project and are they documented on the website? -- Are there user testimonials available? -- Is there an active project blog? -- Are there community talks for the project and are they present on the website? -- Is there a logo wall of users/participating organizations? +- **Are there case studies available for the project and are they documented on the website?** +- **Are there user testimonials available?** +- **Is there an active project blog?** +- **Are there community talks for the project and are they present on the website?** +- **Is there a logo wall of users/participating organizations?** #### SEO, Analytics and site-local search @@ -375,16 +403,16 @@ SEO helps users find your project and it's documentation, and analytics helps yo We evaluate on the following: -- Analytics: - - Is analytics enabled for the production server? - - Is analytics disabled for all other deploys? - - If your project used Google Analytics, have you migrated to GA4? - - Can Page-not-found (404) reports easily be generated from you site - analytics? Provide a sample of the site's current top-10 404s. -- Is site indexing supported for the production server, while disabled for - website previews and builds for non-default branches? -- Is local intra-site search available from the website? -- Are the current custodian(s) of the following accounts clearly documented: +- **Analytics: + - **Is analytics enabled for the production server?** + - **Is analytics disabled for all other deploys?** + - **If your project used Google Analytics, have you migrated to GA4?** + - **Can Page-not-found (404) reports easily be generated from you site + analytics?** Provide a sample of the site's current top-10 404s. +- **Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches?** +- **Is local intra-site search available from the website?** +- **Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) #### Maintenance planning @@ -393,15 +421,15 @@ Website maintenance is an important part of project success, especially when pro We evaluate on the following: -- Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) -- Are you actively cultivating website maintainers from within the community? -- Are site build times reasonable? -- Do site maintainers have adequate permissions? +- **Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?**) +- **Are you actively cultivating website maintainers from within the community?** +- **Are site build times reasonable?** +- **Do site maintainers have adequate permissions?** #### Other -- Is your website accessible via HTTPS? -- Does HTTP access, if any, redirect to HTTPS? +- **Is your website accessible via HTTPS?** +- **Does HTTP access, if any, redirect to HTTPS?** ### Recommendations From e109f3c09429f7a139d2bb55ea229ff537c8c45f Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 3 Mar 2026 15:48:12 +0000 Subject: [PATCH 071/104] chore: move info from top level README to docs readme Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index 4fca64e..88b8685 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,16 +8,15 @@ sidebar_position: 1 This site contains resources provided by the CNCF Technical Documentation team, including: -- Docs about building websites and developing technical documentation, including - recommended tools, best practices, how-tos, and evaluation checklists. It - provides specific guidelines for: +- Docs about building websites and developing technical documentation, + including recommended tools, best practices, how-tos, and evaluation + checklists. It provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - - Analyzing project documentation. - -It also contains a collection of documentation analyses of CNCF projects -performed by the TechDocs team. + - [Analyzing project documentation](./analysis). +- [Analyses](./analyses): a collection of documentation analyses of CNCF projects + performed by the TechDocs team. ## TechDocs Q&A @@ -45,15 +44,15 @@ The full-time staff of the team is: experience, CNCF - [Nate W.](https://github.com/nate-double-u) - Head of mentoring & documentation, CNCF -- [Patrice Chalin](https://github.com/chalin) - Senior TechDocs & webdev lead +- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead - [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses -- Documentation: [CC-BY-4.0](https://github.com/cncf/techdocs/blob/main/LICENSE) -- Code: [Apache-2.0](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE) +- Documentation: [CC-BY-4.0](LICENSE) +- Code: [Apache-2.0](LICENSE-CODE) [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours From d1698486352e957b24dc09431eefa96f752cb05c Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 3 Mar 2026 15:59:43 +0000 Subject: [PATCH 072/104] chore: fix CI errors Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/index.md b/docs/index.md index 88b8685..abda93f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,15 +8,15 @@ sidebar_position: 1 This site contains resources provided by the CNCF Technical Documentation team, including: -- Docs about building websites and developing technical documentation, - including recommended tools, best practices, how-tos, and evaluation - checklists. It provides specific guidelines for: +- Docs about building websites and developing technical documentation, including + recommended tools, best practices, how-tos, and evaluation checklists. It + provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](./analysis). -- [Analyses](./analyses): a collection of documentation analyses of CNCF projects - performed by the TechDocs team. +- [Analyses](./analyses): a collection of documentation analyses of CNCF + projects performed by the TechDocs team. ## TechDocs Q&A @@ -44,7 +44,7 @@ The full-time staff of the team is: experience, CNCF - [Nate W.](https://github.com/nate-double-u) - Head of mentoring & documentation, CNCF -- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead +- [Patrice Chalin](https://github.com/chalin) - Senior TechDocs & webdev lead - [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate Consultants and volunteers also contribute to CNCF TechDocs efforts. From 7c3b34c3bc820a5ab47562ff7b8cd5aca286f957 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Thu, 5 Mar 2026 11:25:28 +0000 Subject: [PATCH 073/104] chore: nit fix Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index abda93f..7668554 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,8 +15,9 @@ including: - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](./analysis). -- [Analyses](./analyses): a collection of documentation analyses of CNCF - projects performed by the TechDocs team. + +It also contains a collection of documentation analyses of CNCF projects +performed by the TechDocs team. ## TechDocs Q&A From 5e94ce3b181fdfd63b98a6bad63fc21a14448b14 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 10 Mar 2026 15:34:32 +0000 Subject: [PATCH 074/104] chore: nit fix Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 7668554..6d837e3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,7 +14,7 @@ including: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - - [Analyzing project documentation](./analysis). + - Analyzing project documentation. It also contains a collection of documentation analyses of CNCF projects performed by the TechDocs team. From dfaf7f43de1c97fd6168a99ad24c3bf94011a44f Mon Sep 17 00:00:00 2001 From: Uchechukwu Obasi Date: Tue, 17 Mar 2026 23:06:03 +0000 Subject: [PATCH 075/104] Chore: Fix all broken links outlined in issue description (#345) * Chore: Fix all broken links outlined in issue description Signed-off-by: thisisobate * chore: format files Signed-off-by: thisisobate * chore: fix markdown error Signed-off-by: thisisobate * chore: fix markdown error Signed-off-by: thisisobate * chore: fix markdown error again Signed-off-by: thisisobate * chore: fix link checker in CI Signed-off-by: thisisobate * chore: add backsticks to link Signed-off-by: thisisobate --------- Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- docs/analysis/templates/analysis.md | 3 +-- docs/index.md | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index cf539c2..f37e7b7 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -550,8 +550,7 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-doc-website]: ./?_PROJECT-DOC-URL_ -[project-website]: ./?_PROJECT-WEBSITE_ +[project-website]: _PROJECT-WEBSITE_ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md diff --git a/docs/index.md b/docs/index.md index 6d837e3..4fca64e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -52,8 +52,8 @@ Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses -- Documentation: [CC-BY-4.0](LICENSE) -- Code: [Apache-2.0](LICENSE-CODE) +- Documentation: [CC-BY-4.0](https://github.com/cncf/techdocs/blob/main/LICENSE) +- Code: [Apache-2.0](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE) [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours From 751d636f47cc95258e8b6aa14098b7f9288cced1 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 00:52:34 -0700 Subject: [PATCH 076/104] Update analysis.md Removed possible formatting build problems Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 39 +++++++++++++------------------ 1 file changed, 16 insertions(+), 23 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 93d2fda..0c1bb82 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -16,7 +16,7 @@ According to CNCF best practices guidelines, effective documentation is a prereq ### Purpose -This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, , outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. +This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. This document: @@ -28,8 +28,7 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the Flatcar GitHub repository. -The Flatcar website and documentation are written in Markdown and are compiled using the "static site" generator with the "theme" and served from "platform". The site's code is stored on the Flatcar GitHub repo. -The Flatcar website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the Flatcar GitHub repo. +The Flatcar website and documentation are written in Markdown and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the Flatcar GitHub repo. #### In scope @@ -39,12 +38,7 @@ The Flatcar website and documentation are written in [Markdown, ReStructured Tex #### Out of scope -Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-website. -- Website repo: https://github.com/cncf/techdocs - -#### Out of scope - -Other Flatcar repos: , for any not listed in "In scope". +Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-webite. ### How this document is organized @@ -348,9 +342,9 @@ Listed here are the minimal website requirements for projects based on their [ma -[git-submodules]: [maturity-level]: - -[cncf-servicedesk]: +git-submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules +maturity-level: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +cncf-servicedesk: https://servicedesk.cncf.io #### Usability, accessibility and devices @@ -362,8 +356,7 @@ Most CNCF websites are accessed from mobile and other non-desktop devices at lea site search and in-page table of contents?** - **Might a [mobile-first] design make sense for your project?** -[mobile-first]: - https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first +[mobile-first](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) Plan for suitable [accessibility][] measures for your website. For example: @@ -373,7 +366,7 @@ Plan for suitable [accessibility][] measures for your website. For example: It is up to each project to set their own guidelines. -[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility +[accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) #### Branding and design @@ -464,11 +457,11 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -[criteria]: ../criteria.md -[implementation]: ./implementation.md -[issues list]: ./issues-list.md -[project-doc-website]: ./?https://www.flatcar.org/docs/latest -[project-website]: ./?https://www.flatcar.org/ -[Rating (1-5)]: #rating-values -[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 -[website guidelines]: ../../website-guidelines-checklist.md +criteria ./criteria.md +implementation ./implementation.md +issues list ./issues-list.md +project-doc-website ./?https://www.flatcar.org/docs/latest +project-website https://www.flatcar.org/ +Rating (1-5) rating-values +rfc-spec https://www.rfc-editor.org/rfc/rfc2119 +website guidelines ../../website-guidelines-checklist.md From d7b2795b16b81fdb66bc62de2f8b116ee036422c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 07:17:26 -0700 Subject: [PATCH 077/104] Update analysis.md Formatting Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 57 +++++++++++++++---------------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 0c1bb82..78e3ffd 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,13 +10,13 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analysis the effectiveness and completeness of the [Flatcar][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. +This document is an analysis the effectiveness and completeness of the [Flatcar](https://www.flatcar.org/docs/latest) open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. ### Purpose -This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second [implementation] document, outlines an actionable plan for improvement. A third document is an [issues list] of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. +This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second **implementation** document, outlines an actionable plan for improvement. A third document is an **issues list** of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. This document: @@ -28,7 +28,7 @@ This document: The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the Flatcar GitHub repository. -The Flatcar website and documentation are written in Markdown and are compiled using the [Hugo, Docusaurus, Sphinx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the Flatcar GitHub repo. +The Flatcar website and documentation are written in Markdown and are compiled using the "static site" generator with the "theme" and served from "platform". The site's code is stored on the Flatcar GitHub repo. #### In scope @@ -53,11 +53,11 @@ Each section begins with summary ratings based on a rubric with appropriate crit - **Comments**: observations about the existing documentation, with a focus on how it does or does not help Flatcar users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. -The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of [issues] and entered as GitHub [project-doc-website]/issues. +The accompanying implementation document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of issues and entered as GitHub project-doc-website/issues. ### How to use this document -Readers interested only in actionable improvements should skip this document and read the **[implementation] plan** and **[issues] list**. +Readers interested only in actionable improvements should skip this document and read the **implementation plan** and **issues list**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: @@ -69,7 +69,7 @@ Examples of CNCF documentation that demonstrate the analysis criteria are linked #### Recommendations, requirements, and best practices -This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-spec], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. +This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of RFCs, the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. ## Project documentation @@ -103,7 +103,7 @@ The "Learning Series" node, introduced into the documentation recently, outlines - The systemd is about core OS management. - The "Container Runtimes" node is an expected node focused on containers and clusters. An argument could be made to elevate "Getting Started with Kubernetes" and "High Availability Kubernetes" to its own node, as Flatcar has its optimization benefits for Kubernetes deployment. - The "Migrating from CoreOS" node might be better placed earlier or within an Installation node, as it is an installation scenario. -- The "Reference" node contains expected look-up information such as "Constance and IDs" and "Supply chain security mechanisms" but these sections could have better placement: +- The "Reference" node contains expected look-up information such as "Constance and IDs" and "Supply chain security mechanisms" but these sections could have better placement: - "Integrations" could be incorporated into the Cloud Providers documentation. - "Developer Guides" contains conceptual content typically not found in a Reference section, so "Developer Guides" or something more descriptive like "Flatcar Development Guides" should be a top-tier node. - The "How to Contribute" node is well-placed has the expected content. @@ -234,9 +234,9 @@ One of the easiest ways to attract new contributors is making sure they know how We evaluate on the following: -- **Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?** +- **Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?** - **Is there a direct link to your GitHub organization/repository?** -- **Are weekly/monthly project meetings documented?** Is it clear how someone can join those meetings?** +- **Are weekly/monthly project meetings documented?** Is it clear how someone can join those meetings?** - **Are mailing lists documented?** #### Beginner friendly issue backlog @@ -244,7 +244,7 @@ We evaluate on the following: We evaluate on the following: - **Are docs issues well-triaged?** -- **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** +- **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** - **Are issues well-documented (i.e., more than just a title)?** - **Are issues maintained for staleness?** @@ -282,11 +282,11 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. +Flatcar is a **graduated** project of CNCF. This means that the project should have high criteria standards for documentation. > AUTHOR NOTE: or -Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ------------------------------------------- | -------------- | @@ -322,7 +322,7 @@ Source files for _all website pages_ should reside in a single repo. Among other - **increases the likelihood of errors - **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][git-submodules]. +Ideally, all website files should be in the **website repo** itself. Alternatively, files should be brought into the website repo via git 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. @@ -335,20 +335,23 @@ Listed here are the minimal website requirements for projects based on their [ma | Criterion | Incubating Requirement | Graduated Requirement | | ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | | [Website guidelines] | All guidelines satisfied | All guidelines satisfied | -| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Docs analysis** (this) | Requested through CNCF service desk | All follow-up actions addressed | | **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | -| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: hosting | Hosted directly | | **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | -git-submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules -maturity-level: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations -cncf-servicedesk: https://servicedesk.cncf.io +[git-submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) +[maturity-level](https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations) +[cncf-servicedesk](https://servicedesk.cncf.io) #### Usability, accessibility and devices -Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. +Most CNCF websites are accessed from mobile and other non-desktop devices. + at least 10-20% of the time. +Planning for this early in your website's design will be much less effort than +retrofitting a desktop-first design. - **Is the website usable from mobile?** - **Are doc pages readable?** @@ -392,7 +395,9 @@ We evaluate on the following: #### 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 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. We evaluate on the following: @@ -414,7 +419,8 @@ Website maintenance is an important part of project success, especially when pro We evaluate on the following: -- **Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?**) +- **Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) +- or commonly used by CNCF projects (our recommended tech stack?**) - **Are you actively cultivating website maintainers from within the community?** - **Are site build times reasonable?** - **Do site maintainers have adequate permissions?** @@ -457,11 +463,4 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -criteria ./criteria.md -implementation ./implementation.md -issues list ./issues-list.md -project-doc-website ./?https://www.flatcar.org/docs/latest -project-website https://www.flatcar.org/ -Rating (1-5) rating-values -rfc-spec https://www.rfc-editor.org/rfc/rfc2119 -website guidelines ../../website-guidelines-checklist.md + From 144415efbabacfa64a52cfb8f73d0142224d1376 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 07:28:23 -0700 Subject: [PATCH 078/104] Update analysis.md Formatting Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 32 +++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 78e3ffd..ad85174 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -328,7 +328,7 @@ If a project chooses to keep source files in multiple repos, they need a clearly #### Minimal website requirements -Listed here are the minimal website requirements for projects based on their [maturity level][maturity-level], either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) +Listed here are the minimal website requirements for projects based on their maturity level, either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) @@ -344,24 +344,24 @@ Listed here are the minimal website requirements for projects based on their [ma [git-submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) [maturity-level](https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations) -[cncf-servicedesk](https://servicedesk.cncf.io) +[service desk](https://servicedesk.cncf.io) #### Usability, accessibility and devices Most CNCF websites are accessed from mobile and other non-desktop devices. - at least 10-20% of the time. -Planning for this early in your website's design will be much less effort than +At least 10-20% of the time. +Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. - **Is the website usable from mobile?** - **Are doc pages readable?** - **Are all / most website features accessible from mobile -- **such as the top-nav, - site search and in-page table of contents?** +site search and in-page table of contents?** - **Might a [mobile-first] design make sense for your project?** [mobile-first](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) -Plan for suitable [accessibility][] measures for your website. For example: +Plan for suitable accessibility measures for your website. For example: - **Are color contrasts significant enough for color-impaired readers?** - **Are most website features usable using a keyboard only?** @@ -369,25 +369,26 @@ Plan for suitable [accessibility][] measures for your website. For example: It is up to each project to set their own guidelines. -[accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) +[Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) #### Branding and design -CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing. +CNCF seeks to support enterprise-ready open source software. We evaluate on the following: -- **Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable?** +- **Is there an easily recognizable brand for the project (logo + color scheme) - **Is the brand used across the website consistently?** - **Is the website’s typography clean and well-suited for reading?** #### Case studies/social proof -One of the best ways to advertise an open source project is to show other organizations using it. +One of the best ways to advertise an open source project is to show other organizations. + We evaluate on the following: -- **Are there case studies available for the project and are they documented on the website?** +- **Are there case studies available for the project and are they documented. - **Are there user testimonials available?** - **Is there an active project blog?** - **Are there community talks for the project and are they present on the website?** @@ -415,12 +416,13 @@ We evaluate on the following: #### Maintenance planning -Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. +Website maintenance is an important part of project success, especially +maintainers aren’t web developers. We evaluate on the following: -- **Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) -- or commonly used by CNCF projects (our recommended tech stack?**) +- **Is your website tooling well-supported by the community. +- Commonly used by CNCF projects (our recommended tech stack?**) - **Are you actively cultivating website maintainers from within the community?** - **Are site build times reasonable?** - **Do site maintainers have adequate permissions?** @@ -462,5 +464,3 @@ The numeric rating values used in this document are as follows 3. Meets standards 4. Meets or exceeds standards 5. Exemplary - - From 92377efe87f4ed1537a853b3c5ec3f07b9117559 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 07:35:45 -0700 Subject: [PATCH 079/104] Update analysis.md Temporarily removed last sections to isolate formatting issue Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 262 ------------------------------ 1 file changed, 262 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index ad85174..bc40d5a 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -202,265 +202,3 @@ No, the complexity of the content is a given, and the content assumes a level of #### Content creation processes #### Inclusive language - -## Contributor documentation - -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -Flatcar is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -Flatcar is an **incubating** project of CNCF. This means that the project should be [_developing_][criteria] professional-quality documentation alongside the project code. - -| Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | -| Communication methods documented | [rating (1-5)] | -| Beginner friendly issue backlog | [rating (1-5)] | -| “New contributor” getting started content | [rating (1-5)] | -| Project governance documentation | [rating (1-5)] | - -### Comments - -> AUTHOR NOTE: make any overall comments about the Contributor Documentation > here. - -The following sections contain brief assessments of each element of the Contributor Documentation rubric. - -> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet > these criteria. Keep in mind that much of the contributor documentation might > be contained in the documentation repository. (Criteria are copied from > criteria.md) - -#### Communication methods documented - -One of the easiest ways to attract new contributors is making sure they know how to reach you. - -We evaluate on the following: - -- **Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website?** -- **Is there a direct link to your GitHub organization/repository?** -- **Are weekly/monthly project meetings documented?** Is it clear how someone can join those meetings?** -- **Are mailing lists documented?** - -#### Beginner friendly issue backlog - -We evaluate on the following: - -- **Are docs issues well-triaged?** -- **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** -- **Are issues well-documented (i.e., more than just a title)?** -- **Are issues maintained for staleness?** - -#### New contributor getting started content - -Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily?** - -We evaluate on the following: - -- **Do you have a community repository or section on your website?** -- **Is there a document specifically for new contributors/your first contribution?** -- **Do new users know where to get help?** - -#### Project governance documentation - -One of the CNCF’s core project values is open governance. - -We evaluate on the following: - -- **Is project governance clearly documented?** - -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. - -#### Communication methods documented - -#### Beginner friendly issue backlog - -#### New contributor getting started content - -#### Project governance documentation - -## Website and infrastructure - -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -Flatcar is a **graduated** project of CNCF. This means that the project should have high criteria standards for documentation. - -> AUTHOR NOTE: or - -Flatcar is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. - -| Criterion | [Rating (1-5)] | -| ------------------------------------------- | -------------- | -| Single-source for all files | [rating (1-5)] | -| Meets min website req. (for maturity level) | [rating (1-5)] | -| Usability, accessibility, and design | [rating (1-5)] | -| Branding and design | [rating (1-5)] | -| Case studies/social proof | [rating (1-5)] | -| SEO, Analytics, and site-local search | [rating (1-5)] | -| Maintenance planning | [rating (1-5)] | -| A11y plan & implementation | [rating (1-5)] | -| Mobile-first plan & impl. | [rating (1-5)] | -| HTTPS access & HTTP redirect | [rating (1-5)] | -| Google Analytics 4 for production only | [rating (1-5)] | -| Indexing allowed for production server only | [rating (1-5)] | -| Intra-site / local search | [rating (1-5)] | -| Account custodians are documented | [rating (1-5)] | - -### Comments - -> AUTHOR NOTE: make any overall comments about the Website and documentation > infrastructure here. - -The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. - -> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet > these criteria. Keep in mind that much of the website infrastructure criteria > depend on the tools (static site generator, website framework and hosting, > analytics tools, etc.) and processes (project CI, release procedures, > governance, etc.) used to produce the documentation. (Criteria are copied from > criteria.md) - -#### Single-source requirement - -Source files for _all website pages_ should reside in a single repo. Among other problems, keeping source files in two places: - -- **confuses contributors -- **requires you to keep two sources in sync -- **increases the likelihood of errors -- **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. - -If a project chooses to keep source files in multiple repos, they need a clearly documented strategy for managing mirrored files and new contributions. - -#### Minimal website requirements - -Listed here are the minimal website requirements for projects based on their maturity level, either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) - - - -| Criterion | Incubating Requirement | Graduated Requirement | -| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | -| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | -| **Docs analysis** (this) | Requested through CNCF service desk | All follow-up actions addressed | -| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | -| **Project doc**: hosting | Hosted directly | -| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | - - - -[git-submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) -[maturity-level](https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations) -[service desk](https://servicedesk.cncf.io) - -#### Usability, accessibility and devices - -Most CNCF websites are accessed from mobile and other non-desktop devices. -At least 10-20% of the time. -Planning for this early in your website's design will be much less effort than -retrofitting a desktop-first design. - -- **Is the website usable from mobile?** -- **Are doc pages readable?** -- **Are all / most website features accessible from mobile -- **such as the top-nav, -site search and in-page table of contents?** -- **Might a [mobile-first] design make sense for your project?** - -[mobile-first](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) - -Plan for suitable accessibility measures for your website. For example: - -- **Are color contrasts significant enough for color-impaired readers?** -- **Are most website features usable using a keyboard only?** -- **Does text-to-speech offer listeners a good experience?** - -It is up to each project to set their own guidelines. - -[Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) - -#### Branding and design - -CNCF seeks to support enterprise-ready open source software. - -We evaluate on the following: - -- **Is there an easily recognizable brand for the project (logo + color scheme) -- **Is the brand used across the website consistently?** -- **Is the website’s typography clean and well-suited for reading?** - -#### Case studies/social proof - -One of the best ways to advertise an open source project is to show other organizations. - - -We evaluate on the following: - -- **Are there case studies available for the project and are they documented. -- **Are there user testimonials available?** -- **Is there an active project blog?** -- **Are there community talks for the project and are they present on the website?** -- **Is there a logo wall of users/participating organizations?** - -#### 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. - -We evaluate on the following: - -- **Analytics: - - **Is analytics enabled for the production server?** - - **Is analytics disabled for all other deploys?** - - **If your project used Google Analytics, have you migrated to GA4?** - - **Can Page-not-found (404) reports easily be generated from you site - analytics?** Provide a sample of the site's current top-10 404s. -- **Is site indexing supported for the production server, while disabled for - website previews and builds for non-default branches?** -- **Is local intra-site search available from the website?** -- **Are the current custodian(s) of the following accounts clearly documented: - analytics, Google Search Console, site-search (such as Google CSE or Algolia) - -#### Maintenance planning - -Website maintenance is an important part of project success, especially -maintainers aren’t web developers. - -We evaluate on the following: - -- **Is your website tooling well-supported by the community. -- Commonly used by CNCF projects (our recommended tech stack?**) -- **Are you actively cultivating website maintainers from within the community?** -- **Are site build times reasonable?** -- **Do site maintainers have adequate permissions?** - -#### Other - -- **Is your website accessible via HTTPS?** -- **Does HTTP access, if any, redirect to HTTPS?** - -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - -#### Single-source requirement - -#### Minimal website requirements - -#### Usability, accessibility and devices - -#### Branding and design - -#### Case studies/social proof - -#### SEO, Analytics and site-local search - -#### Maintenance planning - -#### Other - -#### References and notes - -##### Rating values - -The numeric rating values used in this document are as follows - -1. Not present -2. Needs improvement -3. Meets standards -4. Meets or exceeds standards -5. Exemplary From 8d2e4f73fac096bec0794e7c46a4fb187d1b1220 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 07:56:04 -0700 Subject: [PATCH 080/104] Update analysis.md More formatting tests Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index bc40d5a..1964d76 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -38,7 +38,7 @@ The Flatcar website and documentation are written in Markdown and are compiled u #### Out of scope -Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-webite. +Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-website. ### How this document is organized @@ -191,8 +191,6 @@ No, the complexity of the content is a given, and the content assumes a level of ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the > previous section. - #### Information architecture #### New user content From 66e9eaddcb5d4121e72e7db68afeee8c6f9cbef9 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 3 Mar 2026 15:48:12 +0000 Subject: [PATCH 081/104] chore: move info from top level README to docs readme Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton --- docs/index.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index 4fca64e..88b8685 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,16 +8,15 @@ sidebar_position: 1 This site contains resources provided by the CNCF Technical Documentation team, including: -- Docs about building websites and developing technical documentation, including - recommended tools, best practices, how-tos, and evaluation checklists. It - provides specific guidelines for: +- Docs about building websites and developing technical documentation, + including recommended tools, best practices, how-tos, and evaluation + checklists. It provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - - Analyzing project documentation. - -It also contains a collection of documentation analyses of CNCF projects -performed by the TechDocs team. + - [Analyzing project documentation](./analysis). +- [Analyses](./analyses): a collection of documentation analyses of CNCF projects + performed by the TechDocs team. ## TechDocs Q&A @@ -45,15 +44,15 @@ The full-time staff of the team is: experience, CNCF - [Nate W.](https://github.com/nate-double-u) - Head of mentoring & documentation, CNCF -- [Patrice Chalin](https://github.com/chalin) - Senior TechDocs & webdev lead +- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead - [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses -- Documentation: [CC-BY-4.0](https://github.com/cncf/techdocs/blob/main/LICENSE) -- Code: [Apache-2.0](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE) +- Documentation: [CC-BY-4.0](LICENSE) +- Code: [Apache-2.0](LICENSE-CODE) [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours From c04c7bc459eed0362d8adf5e8ccc2e6a73198237 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 3 Mar 2026 15:59:43 +0000 Subject: [PATCH 082/104] chore: fix CI errors Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton --- docs/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/index.md b/docs/index.md index 88b8685..abda93f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,15 +8,15 @@ sidebar_position: 1 This site contains resources provided by the CNCF Technical Documentation team, including: -- Docs about building websites and developing technical documentation, - including recommended tools, best practices, how-tos, and evaluation - checklists. It provides specific guidelines for: +- Docs about building websites and developing technical documentation, including + recommended tools, best practices, how-tos, and evaluation checklists. It + provides specific guidelines for: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](./analysis). -- [Analyses](./analyses): a collection of documentation analyses of CNCF projects - performed by the TechDocs team. +- [Analyses](./analyses): a collection of documentation analyses of CNCF + projects performed by the TechDocs team. ## TechDocs Q&A @@ -44,7 +44,7 @@ The full-time staff of the team is: experience, CNCF - [Nate W.](https://github.com/nate-double-u) - Head of mentoring & documentation, CNCF -- [Patrice Chalin](https://github.com/chalin) - Senior techdoc & webdev lead +- [Patrice Chalin](https://github.com/chalin) - Senior TechDocs & webdev lead - [Uchechukwu Obasi](https://github.com/thisisobate) - Developer advocate Consultants and volunteers also contribute to CNCF TechDocs efforts. From 8941491e904a88f238e013cc4a6a3db6b3b8b388 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Thu, 5 Mar 2026 11:25:28 +0000 Subject: [PATCH 083/104] chore: nit fix Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton --- docs/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index abda93f..7668554 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,8 +15,9 @@ including: - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - [Analyzing project documentation](./analysis). -- [Analyses](./analyses): a collection of documentation analyses of CNCF - projects performed by the TechDocs team. + +It also contains a collection of documentation analyses of CNCF projects +performed by the TechDocs team. ## TechDocs Q&A From ad08ec337e42f9a14a3e394b3f472e4d25dd7835 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 10 Mar 2026 15:34:32 +0000 Subject: [PATCH 084/104] chore: nit fix Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 7668554..6d837e3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,7 +14,7 @@ including: - Setting up and maintaining a documentation website. - Writing technical documentation for a project. - Seeking assistance from the CNCF TechDocs community. - - [Analyzing project documentation](./analysis). + - Analyzing project documentation. It also contains a collection of documentation analyses of CNCF projects performed by the TechDocs team. From 51badcf36a25501c5a5fa0cc3360e7130c135886 Mon Sep 17 00:00:00 2001 From: Uchechukwu Obasi Date: Tue, 17 Mar 2026 23:06:03 +0000 Subject: [PATCH 085/104] Chore: Fix all broken links outlined in issue description (#345) * Chore: Fix all broken links outlined in issue description Signed-off-by: thisisobate * chore: format files Signed-off-by: thisisobate * chore: fix markdown error Signed-off-by: thisisobate * chore: fix markdown error Signed-off-by: thisisobate * chore: fix markdown error again Signed-off-by: thisisobate * chore: fix link checker in CI Signed-off-by: thisisobate * chore: add backsticks to link Signed-off-by: thisisobate --------- Signed-off-by: thisisobate Signed-off-by: Bruce Hamilton --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6d837e3..4fca64e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -52,8 +52,8 @@ Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses -- Documentation: [CC-BY-4.0](LICENSE) -- Code: [Apache-2.0](LICENSE-CODE) +- Documentation: [CC-BY-4.0](https://github.com/cncf/techdocs/blob/main/LICENSE) +- Code: [Apache-2.0](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE) [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours From 6a19e267f87a927f9ec4155cf4e263c573666f5b Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 09:49:57 -0700 Subject: [PATCH 086/104] Used Prittier extension Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 323 +++++++++++++++++++++++------- 1 file changed, 253 insertions(+), 70 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 1964d76..9d47f62 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,13 +10,25 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analysis the effectiveness and completeness of the [Flatcar](https://www.flatcar.org/docs/latest) open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. +This document is an analysis the effectiveness and completeness of the +[Flatcar](https://www.flatcar.org/docs/latest) open source software (OSS) +project's documentation and website. It is funded by the CNCF Foundation as part +of its overall effort to incubate, grow, and graduate open source cloud native +software projects. -According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. +According to CNCF best practices guidelines, effective documentation is a +prerequisite for program graduation. The documentation analysis is the first +step of a CNCF process aimed at assisting projects with their documentation +efforts. ### Purpose -This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second **implementation** document, outlines an actionable plan for improvement. A third document is an **issues list** of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. +This document was written to analyze the current state of Flatcar documentation. +It aims to provide project leaders with an informed understanding of potential +problems in current project documentation. A second **implementation** document, +outlines an actionable plan for improvement. A third document is an **issues +list** of issues to be added to the project documentation repository. These +issues can be taken up by contributors to improve the documentation. This document: @@ -26,9 +38,13 @@ This document: ### Scope of analysis -The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the Flatcar GitHub repository. +The documentation discussed here includes the entire contents of the website, +the technical documentation, and documentation for contributors and users on the +Flatcar GitHub repository. -The Flatcar website and documentation are written in Markdown and are compiled using the "static site" generator with the "theme" and served from "platform". The site's code is stored on the Flatcar GitHub repo. +The Flatcar website and documentation are written in Markdown and are compiled +using the "static site" generator with the "theme" and served from "platform". +The site's code is stored on the Flatcar GitHub repo. #### In scope @@ -38,42 +54,67 @@ The Flatcar website and documentation are written in Markdown and are compiled u #### Out of scope -Other Flatcar besides the flatcar-website: https://github.com/flatcar/flatcar-website. +Other Flatcar besides the flatcar-website: +https://github.com/flatcar/flatcar-website. ### How this document is organized -This document is divided into three sections that represent three major areas of concern: +This document is divided into three sections that represent three major areas of +concern: -- **Project documentation:** concerns documentation for users of the Flatcar software, aimed at people who intend to use the project software -- **Contributor documentation:** concerns documentation for new and existing contributors to the Flatcar OSS project -- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability +- **Project documentation:** concerns documentation for users of the Flatcar + software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Flatcar OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability -Each section begins with summary ratings based on a rubric with appropriate criteria for the section, then proceeds to: +Each section begins with summary ratings based on a rubric with appropriate +criteria for the section, then proceeds to: -- **Comments**: observations about the existing documentation, with a focus on how it does or does not help Flatcar users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness of the documentation. +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help Flatcar users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. -The accompanying implementation document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed into a series of issues and entered as GitHub project-doc-website/issues. +The accompanying implementation document breaks the recommendations down into +concrete actions that can be implemented by project contributors. Its focus is +on drilling down to specific, achievable work that can be completed in +constrained blocks of time. Ultimately, the implementation items are decomposed +into a series of issues and entered as GitHub project-doc-website/issues. ### How to use this document -Readers interested only in actionable improvements should skip this document and read the **implementation plan** and **issues list**. +Readers interested only in actionable improvements should skip this document and +read the **implementation plan** and **issues list**. -Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: - [Project documentation](https://www.flatcar.org/docs/latest) - [Contributor documentation](https://www.flatcar.org/docs/latest/contribute/) - [Website and documentation infrastructure](https://github.com/flatcar/flatcar-website) -Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria] specification. #### Recommendations, requirements, and best practices -This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, the recommended implementations represent the reviewers' experience with how to apply documentation best practices. In other words, borrowing terminology from the lexicon of RFCs, the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. +This analysis measures documentation against CNCF project maturity standards, +and suggests possible improvements. In most cases there is more than one way to +do things. Few recommendations here are meant to be prescriptive. Rather, the +recommended implementations represent the reviewers' experience with how to +apply documentation best practices. In other words, borrowing terminology from +the lexicon of RFCs, the changes described here should be understood as +"recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. ## Project documentation -Flatcar is an **incubating** project of CNCF. This means that the project should be developing professional-quality documentation alongside the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should +be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | -------------------------- | -------------- | @@ -85,85 +126,223 @@ Flatcar is an **incubating** project of CNCF. This means that the project should ### Comments -The following sections contain brief assessments of each element of the project documentation. - -The current Flatcar documentation table of contents defines the needed areas of knowledge to install and provision Flatcar, but it does not readily show the different paths for new users depending on their environment. - -The following comments regard the top-tier nodes in the current table of contents: - -- The top overview page contains headings with short paragraphs and links that provide additional views and categorization of Flatcar topics. These links are not necessarily parallel with the table of contents hierarchy. -- The "Installing" node Overview page introduces the needed guidance for the provisioning and configuration of Flatcar, but it also contains getting started code for a VM installation. That content is better served by a Getting Started node or the Learning Series node. -- The "Installing" node contains the large "Cloud Providers" node, that might be better as top tier node, same with "Bare Metal". The team agrees that "Community supported platforms" could be merged into the Cloud Providers node. The installation node should be primarily addressing all the new user paths, providing an installation roadmap or strategy. -The "Learning Series" node, introduced into the documentation recently, outlines the key steps for installing, configuring, and managing Flatcar conveying the life cycle. It would be good for the top nodes to have a similar flow. -- The "Provisioning Tools" title is descriptive, but its unclear how other areas of the docs relate to this section. -- The "Nebraska" node is about updates, but it should convey the functionality and its location is unusual prominence. -- The "Setup and Operations" node is too much of a wide net in its title. How does "setup" differ from installation? The node contains several important content areas that should be more discoverable, for instance: - - "Managing Clusters" might be better at a higher level because it's an initial evaluation of whether to deploy Flatcar. +The following sections contain brief assessments of each element of the project +documentation. + +The current Flatcar documentation table of contents defines the needed areas of +knowledge to install and provision Flatcar, but it does not readily show the +different paths for new users depending on their environment. + +The following comments regard the top-tier nodes in the current table of +contents: + +- The top overview page contains headings with short paragraphs and links that + provide additional views and categorization of Flatcar topics. These links are + not necessarily parallel with the table of contents hierarchy. +- The "Installing" node Overview page introduces the needed guidance for the + provisioning and configuration of Flatcar, but it also contains getting + started code for a VM installation. That content is better served by a Getting + Started node or the Learning Series node. +- The "Installing" node contains the large "Cloud Providers" node, that might be + better as top tier node, same with "Bare Metal". The team agrees that + "Community supported platforms" could be merged into the Cloud Providers node. + The installation node should be primarily addressing all the new user paths, + providing an installation roadmap or strategy. The "Learning Series" node, + introduced into the documentation recently, outlines the key steps for + installing, configuring, and managing Flatcar conveying the life cycle. It + would be good for the top nodes to have a similar flow. +- The "Provisioning Tools" title is descriptive, but its unclear how other areas + of the docs relate to this section. +- The "Nebraska" node is about updates, but it should convey the functionality + and its location is unusual prominence. +- The "Setup and Operations" node is too much of a wide net in its title. How + does "setup" differ from installation? The node contains several important + content areas that should be more discoverable, for instance: + - "Managing Clusters" might be better at a higher level because it's an + initial evaluation of whether to deploy Flatcar. - The Storage and Security nodes are typically at a higher level. - The systemd is about core OS management. -- The "Container Runtimes" node is an expected node focused on containers and clusters. An argument could be made to elevate "Getting Started with Kubernetes" and "High Availability Kubernetes" to its own node, as Flatcar has its optimization benefits for Kubernetes deployment. -- The "Migrating from CoreOS" node might be better placed earlier or within an Installation node, as it is an installation scenario. -- The "Reference" node contains expected look-up information such as "Constance and IDs" and "Supply chain security mechanisms" but these sections could have better placement: +- The "Container Runtimes" node is an expected node focused on containers and + clusters. An argument could be made to elevate "Getting Started with + Kubernetes" and "High Availability Kubernetes" to its own node, as Flatcar has + its optimization benefits for Kubernetes deployment. +- The "Migrating from CoreOS" node might be better placed earlier or within an + Installation node, as it is an installation scenario. +- The "Reference" node contains expected look-up information such as "Constance + and IDs" and "Supply chain security mechanisms" but these sections could have + better placement: - "Integrations" could be incorporated into the Cloud Providers documentation. - - "Developer Guides" contains conceptual content typically not found in a Reference section, so "Developer Guides" or something more descriptive like "Flatcar Development Guides" should be a top-tier node. + - "Developer Guides" contains conceptual content typically not found in a + Reference section, so "Developer Guides" or something more descriptive like + "Flatcar Development Guides" should be a top-tier node. - The "How to Contribute" node is well-placed has the expected content. -The documentation also includes an FAQ, accessible from the top banner of the home page. It has some content that would be good to verify that its in the main docs, such as historical context and how images are updated. Conversely, there should be a few top-of-mind installation and support FAQ items derived from the docs. +The documentation also includes an FAQ, accessible from the top banner of the +home page. It has some content that would be good to verify that its in the main +docs, such as historical context and how images are updated. Conversely, there +should be a few top-of-mind installation and support FAQ items derived from the +docs. + +Code blocks are different from other documentation sets as they are not bordered +or have a different fill background, don't have a copy button, and the language +is not noted. + +New users might not be sure of the context for a given block of code. Is the +Linux prompt in a VM, in a client computer, or in a CLI session with a cloud +provider? Normally this can be deduced by the narrative, but starting a +procedure with "In the VM window, use the following command to ..." or similar +guidance. + +It should be noted that a new proposed structure is proposed by the team, with +the top nodes as follows: + +Flatcar Concepts and Quick Start Configuration and Provisioning Deploying to +Public Cloud, Private Cloud, and Bare Metal Kubernetes In-place updates and +roll-backs The Nebraska update server Customizing and Extending the OS image +Troubleshooting Developer Guides Legacy Information + +Essentially all the pertinent areas of knowledge to install and run Flatcar have +been identified and documented. Then just need to be better organized. The next +step is to structure the documentation so that it meets these objectives: + +- The node and topic titles provide expected guidance, such as "Getting + Started", with nodes and sections organized for precise purposes, rather than + headings that serve as broad categories such as "Setup and Operations". +- The structure provides the expected flow and orientation of users so that they + can identify a pathway for learning about and deploying Flatcar efficiently + and optimally. +- The structure provides effective navigation and identification of the tools + and technologies so that users efficiently learn about the ones they need to + use. + +#### Information architecture -Code blocks are different from other documentation sets as they are not bordered or have a different fill background, don't have a copy button, and the language is not noted. +The overall structure (pages/subpages/sections/subsections) of your project +documentation. We evaluate on the following: -New users might not be sure of the context for a given block of code. Is the Linux prompt in a VM, in a client computer, or in a CLI session with a cloud provider? Normally this can be deduced by the narrative, but starting a procedure with "In the VM window, use the following command to ..." or similar guidance. +##### Is there high-level conceptual or About content? -It should be noted that a new proposed structure is proposed by the team, with the top nodes as follows: +The current content is comprehensive on the key concepts needed for +understanding the processes and technologies involved. It's just a matter of +organizing discussion of the concepts to map to the user the path for installing +and configuring Flatcar. - Flatcar Concepts and Quick Start - Configuration and Provisioning - Deploying to Public Cloud, Private Cloud, and Bare Metal - Kubernetes - In-place updates and roll-backs - The Nebraska update server - Customizing and Extending the OS image - Troubleshooting - Developer Guides - Legacy Information +- **Is the documentation feature complete?** -Essentially all the pertinent areas of knowledge to install and run Flatcar have been identified and documented. Then just need to be better organized. The next step is to structure the documentation so that it meets these objectives: + Yes, given that Flatcar is essentially an operating system and new features + and capabilities will be apparent and easily referenced. -- The node and topic titles provide expected guidance, such as "Getting Started", with nodes and sections organized for precise purposes, rather than headings that serve as broad categories such as "Setup and Operations". -- The structure provides the expected flow and orientation of users so that they can identify a pathway for learning about and deploying Flatcar efficiently and optimally. -- The structure provides effective navigation and identification of the tools and technologies so that users efficiently learn about the ones they need to use. +- **Are there step-by-step instructions (tasks, tutorials) documented for + features?** -#### Information architecture + Procedures, mainly invoking bash commands, are introduced informally and do + not have the typical Microsoft style of numbered steps that read "Use the + following command to ..." verbiage. It would be easy to rewrite for meet that + conformity. -The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: +- **Are there any key features which are documented but missing task + documentation?** -##### Is there high-level conceptual or About content? + Not so much regarding features, but there are tasks in using provisioning + tools where step-by-step guidance would be appreciated. -The current content is comprehensive on the key concepts needed for understanding the processes and technologies involved. It's just a matter of organizing discussion of the concepts to map to the user the path for installing and configuring Flatcar. +- **Are tasks clearly named according to user goals providing a happy path for + users to get their tasks accomplished?** -New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: + Not currently. But the needed content areas are established and just need to + be coordinated into a "Flatcar installation roadmap" for most paths. + +- **If the documentation does not suffice, is there a clear escalation path for + users needing more help? (FAQ)** + + There is an FAQ that needs updating. + +- **If the product exposes an API, is there a complete reference?** + + There is a Developer Guide for building Flatcar Container Linux from source + and/or in modifying the OS. The SDK is a containerized Software Development + Kit that enables developers to customize and build their own Flatcar Container + Linux OS images. + + The SDK is not an API with function calls, but rather a kit of scripts and + tools. + +##### New user content + +New users are the most avid users of documentation, and need content +specifically for them. We evaluate on the following: - **Is “getting started” or similar clearly labeled?** -- **Are there step-by-step instructions (tasks, tutorials) documented for features?** +The "Learning Series" is a well-documented getting started guide. There is a +Heading 3 heading "Getting started" in the overview. + +- **Is installation documented step-by-step?** -As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. +Procedures are not formal step-by-steps, but rather sufficient descriptions of +the purpose and result of running the provided code example. + +Even if the new user does not know anything about the technologies, it can still +be logical and understandable by looking up terms. + +- **If needed, are multiple OSes documented?** + +Users are typically running a Linux machine, or a VM running on Windows or +MacOS. It would be beneficial to acquaint the user with any client OS guidance, +particularly when installing tools and images. + +- **Do users know where to go after reading the getting started guide?** + +Intuitively perhaps, as the Learning Services provides sufficient content to get +Flatcar instances running. It would be good to have listings of next steps for +the various deployment scenarios. + +- **Is your new user content clearly signposted on your site’s homepage or at + the top of your information architecture?** + +Other than being a top level node in the table of contents, no. + +- **Is there sample code or other example content that can easily be + copy-pasted?** + +Yes, most pages have code samples, but currently the UI does not show code +example blocks with copy buttons. The code is simply in a different font. + +##### Content maintainability & site mechanics + +As a project scales, concerns like localized (translated) content and versioning +become large maintenance burdens, particularly if you don’t plan for them. We evaluate on the following: - **Is your documentation searchable?** -Yes, the home page has a search bar where any results populate a dropdown for selection. +Yes, the home page has a search bar where any results populate a dropdown for +selection. + +- **Are you planning for localization/internationalization?** + +There are currently no plans for localization. + +- **Do you have a clearly documented method for versioning your content?** + +Being an incubating project, the content is not versioned at this time. + +##### Content creation processes -Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. +Documentation is only as useful as it is accurate and well-maintained, and +requires the same kind of review and approval processes as code. We evaluate on the following: -- **Is there a clearly documented (ongoing) contribution process for documentation?** +- **Is there a clearly documented (ongoing) contribution process for + documentation?** -Yes. There is a 'How to contribute' node with guidance for using the GitHub repository, formatting, and style. +Yes. There is a 'How to contribute' node with guidance for using the GitHub +repository, formatting, and style. -- **Does your code release process account for documentation creation & updates?** +- **Does your code release process account for documentation creation & + updates?** Supported, but not a formalized process at this time. @@ -181,13 +360,17 @@ Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: -- **Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website?** +- **Are there any customer-facing utilities, endpoints, class names, or feature + names that use non-recommended words as documented by the + [Inclusive Naming Initiative](https://inclusivenaming.org) website?** -The 175 hits were "master", "disable", "abort", and "man in the middle". Of those only "abort" would necessitate a fix on eight occurrences. +The 175 hits were "master", "disable", "abort", and "man in the middle". Of +those only "abort" would necessitate a fix on eight occurrences. - **Does the project use language like "simple", "easy", etc.?** -No, the complexity of the content is a given, and the content assumes a level of sophistication where such verbiage would be suspicious. +No, the complexity of the content is a given, and the content assumes a level of +sophistication where such verbiage would be suspicious. ### Recommendations From c99970276c9eeed0c9689fc94a208060718e1d3e Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 11:44:11 -0700 Subject: [PATCH 087/104] link edits Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 9d47f62..bb17b92 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -92,9 +92,9 @@ Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: -- [Project documentation](https://www.flatcar.org/docs/latest) -- [Contributor documentation](https://www.flatcar.org/docs/latest/contribute/) -- [Website and documentation infrastructure](https://github.com/flatcar/flatcar-website) +- [Project documentation](#project-documentation) +- Contributor documentation +- Website and documentation infrastructure Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. From 9d98c0c6e6774a81df9f26011589d631491db8b1 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 13:21:03 -0700 Subject: [PATCH 088/104] minor edit to rebuild Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index bb17b92..048b1c8 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -383,3 +383,5 @@ sophistication where such verbiage would be suspicious. #### Content creation processes #### Inclusive language + +Remaineder of template to be applied. From 5d4dad4d5b0d947f6224dd4a0a8c8346f9ab7a37 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Date: Mon, 30 Mar 2026 13:26:28 -0700 Subject: [PATCH 089/104] spelling fix Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 048b1c8..2c92934 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -384,4 +384,4 @@ sophistication where such verbiage would be suspicious. #### Inclusive language -Remaineder of template to be applied. +Remainder of template to be applied. From 642800e971a578565f7aaef51b922c7aa4102b81 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 30 Mar 2026 15:29:42 -0700 Subject: [PATCH 090/104] edit to rebuild Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 2c92934..bb17b92 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -383,5 +383,3 @@ sophistication where such verbiage would be suspicious. #### Content creation processes #### Inclusive language - -Remainder of template to be applied. From 237557104a1b8f810a9c1bde9196990cef720b44 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 30 Mar 2026 17:35:51 -0700 Subject: [PATCH 091/104] Link edits Signed-off-by: Bruce Hamilton --- docs/analytics/index.md | 8 ++++---- docs/analytics/ua-to-ga4.md | 31 ++++++++++++++----------------- 2 files changed, 18 insertions(+), 21 deletions(-) diff --git a/docs/analytics/index.md b/docs/analytics/index.md index 1a59940..6783971 100644 --- a/docs/analytics/index.md +++ b/docs/analytics/index.md @@ -19,7 +19,7 @@ title: Analytics > Analytics to GA4, see > [Migrating Universal to Google Analytics 4](ua-to-ga4.md). -[CNCF sandbox]: https://github.com/cncf/sandbox -[docsy]: https://www.docsy.dev -[ga4]: https://support.google.com/analytics/answer/10089681 -[service desk]: https://github.com/cncf/servicedesk +[CNCF sandbox](https://github.com/cncf/sandbox) +[docsy](https://www.docsy.dev) +[ga4](https://support.google.com/analytics/answer/10089681) +[service desk](https://github.com/cncf/servicedesk) diff --git a/docs/analytics/ua-to-ga4.md b/docs/analytics/ua-to-ga4.md index 1b6bbf5..18af9ad 100644 --- a/docs/analytics/ua-to-ga4.md +++ b/docs/analytics/ua-to-ga4.md @@ -168,20 +168,17 @@ project's GA4 measurement ID. Details are provided in Adding Analytics. Of course, this may require you to upgrade the version of [Docsy][] and/or Hugo that your project is using. -[add gtag.js to your site]: - https://developers.google.com/analytics/devguides/collection/gtagjs/ -[analytics.js]: https://support.google.com/analytics/answer/10268458 -[connected]: https://support.google.com/analytics/answer/9973999 -[docsy]: https://www.docsy.dev -[docusaurus]: https://docusaurus.io/ -[ga4-dev]: https://developers.google.com/analytics/devguides/migration -[ga4]: https://support.google.com/analytics/answer/10089681 -[ga4+ua-dev]: - https://developers.google.com/analytics/devguides/migration/measurement/add-ga4 -[gtag.js]: https://support.google.com/analytics/answer/10220869 -[issue #108]: https://github.com/cncf/techdocs/issues/108 -[migration-help]: https://support.google.com/analytics/answer/10759417 -[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 +[add gtag.js to your site](https://developers.google.com/analytics/devguides/collection/gtagjs/) +[analytics.js](https://support.google.com/analytics/answer/10268458) +[connected](https://support.google.com/analytics/answer/9973999) +[docsy](https://www.docsy.dev) +[docusaurus](https://docusaurus.io/) +[ga4-dev](https://developers.google.com/analytics/devguides/migration) +[ga4](https://support.google.com/analytics/answer/10089681) +[ga4+ua-dev](https://developers.google.com/analytics/devguides/migration/measurement/add-ga4) +[gtag.js](https://support.google.com/analytics/answer/10220869) +[issue #108](https://github.com/cncf/techdocs/issues/108) +[migration-help](https://support.google.com/analytics/answer/10759417) +stage 2: #stage-2---configure-the-ga4-id-as-the-main-analytics-id +[status table](https://docs.google.com/spreadsheets/d/Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA) +[ua](https://support.google.com/analytics/answer/11583528) From c45e8c9d212b4761a16e20246fe42610a8e087cc Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 30 Mar 2026 19:41:20 -0400 Subject: [PATCH 092/104] Update Docsy feedback links, htmltest & refcache (#347) Reduce htmltest CacheExpires to ~6 months, update docsy analytics link paths in analytics docs to /docs/content/feedback/#adding-analytics, and refresh static/refcache.json (LastSeen timestamps, some status codes, and a new GitHub ref entry). These changes keep link references current and shorten cache expiry for HTML tests. Signed-off-by: Patrice Chalin Signed-off-by: Bruce Hamilton --- .htmltest.yml | 2 +- static/refcache.json | 236 ++++++++++++++++++++++--------------------- 2 files changed, 121 insertions(+), 117 deletions(-) diff --git a/.htmltest.yml b/.htmltest.yml index ea46cd5..46e52b8 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -1,5 +1,5 @@ # cSpell:ignore github -CacheExpires: 9000h # ~ 12 months +CacheExpires: 4500h # ~ 6 months DirectoryPath: build TestFilesConcurrently: true IgnoreDirs: diff --git a/static/refcache.json b/static/refcache.json index 82bdf37..fc34510 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -1,19 +1,19 @@ { "https://analytics.google.com": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:43.150103-04:00" + "LastSeen": "2026-03-30T15:42:08.467987-04:00" }, "https://blog.rook.io/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:43.211822-04:00" + "LastSeen": "2026-03-30T15:50:24.152457-04:00" }, "https://cloud-native.slack.com": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:42.798322-04:00" + "LastSeen": "2026-03-30T15:42:18.773037-04:00" }, "https://cloud-native.slack.com/archives/C057F81GFUG": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:43.065916-04:00" + "LastSeen": "2026-03-30T15:42:19.40547-04:00" }, "https://cncf-techdocs.netlify.app/": { "StatusCode": 206, @@ -117,119 +117,123 @@ }, "https://creativecommons.org/licenses/by/4.0/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.210818-04:00" + "LastSeen": "2026-03-30T15:42:05.214193-04:00" }, "https://developer.mozilla.org/en-US/docs/Web/Accessibility": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.847102-04:00" + "LastSeen": "2026-03-30T15:42:07.126948-04:00" }, "https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.5755-04:00" + "LastSeen": "2026-03-30T15:42:06.854488-04:00" }, "https://developers.google.com": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:40.68391-04:00" + "LastSeen": "2026-03-30T15:42:08.334708-04:00" }, "https://developers.google.com/analytics/devguides/collection/gtagjs/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:45.186799-04:00" + "LastSeen": "2026-03-30T15:42:10.823616-04:00" }, "https://developers.google.com/analytics/devguides/migration": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:40.365597-04:00" + "LastSeen": "2026-03-30T15:42:04.770291-04:00" }, "https://developers.google.com/analytics/devguides/migration/measurement/add-ga4": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:41.008153-04:00" + "LastSeen": "2026-03-30T15:42:05.801394-04:00" }, "https://developers.google.com/custom-search/docs/overview": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:38.568984-04:00" + "LastSeen": "2026-03-30T15:42:03.327195-04:00" }, "https://developers.google.com/tech-writing": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:41.235297-04:00" + "LastSeen": "2026-03-30T15:42:09.240702-04:00" }, "https://discourse.gohugo.io/t/audit-your-published-site-for-problems/35184": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:38.673658-04:00" + "LastSeen": "2026-03-30T15:42:03.321157-04:00" }, "https://docs.github.com/en/get-started": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.550448-04:00" + "LastSeen": "2026-03-30T15:42:05.161319-04:00" }, "https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.974872-04:00" + "LastSeen": "2026-03-30T15:42:12.284749-04:00" }, "https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:40.556759-04:00" + "LastSeen": "2026-03-30T15:42:05.093688-04:00" }, "https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:43.824829-04:00" + "LastSeen": "2026-03-30T15:42:09.171241-04:00" }, "https://docs.netlify.com/domains-https/custom-domains/multiple-domains/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.56912-04:00" + "LastSeen": "2026-03-30T15:42:07.340443-04:00" }, "https://docs.netlify.com/domains-https/netlify-dns/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.528687-04:00" + "LastSeen": "2026-03-30T15:42:06.919207-04:00" }, "https://docsearch.algolia.com/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.903227-04:00" + "LastSeen": "2026-03-30T15:42:04.078587-04:00" }, "https://docsfordevelopers.com/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:41.327555-04:00" + "LastSeen": "2026-03-30T15:42:09.45585-04:00" }, "https://docusaurus.io/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:44.454182-04:00" + "LastSeen": "2026-03-30T15:42:10.06588-04:00" }, "https://expertsupport.com/library/quick-and-easy-document-specifications/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:39.609931-04:00" + "LastSeen": "2026-03-30T15:42:05.188444-04:00" }, "https://falco.org/docs/getting-started/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.973046-04:00" + "LastSeen": "2026-03-30T15:42:04.808268-04:00" }, "https://git-scm.com/book/en/v2/Git-Tools-Submodules": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.523542-04:00" + "LastSeen": "2026-03-30T15:42:05.031791-04:00" }, "https://github.com/Okabe-Junya": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.433444-04:00" + "LastSeen": "2026-03-30T15:42:06.598873-04:00" }, "https://github.com/apps/dco": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.188531-04:00" + "LastSeen": "2026-03-30T15:42:05.113695-04:00" }, "https://github.com/brianpursley": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.819634-04:00" + "LastSeen": "2026-03-30T15:42:11.984654-04:00" }, "https://github.com/caniszczyk": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.673482-04:00" + "LastSeen": "2026-03-30T15:42:03.737588-04:00" }, "https://github.com/carlisia": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.066678-04:00" + "LastSeen": "2026-03-30T15:42:10.694129-04:00" }, "https://github.com/celestehorgan": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:43.110802-04:00" + "LastSeen": "2026-03-30T15:42:12.434807-04:00" }, "https://github.com/chalin": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.933773-04:00" + "LastSeen": "2026-03-30T15:42:05.637961-04:00" + }, + "https://github.com/cncf/foundation/blob/main/policies-guidance/website-guidelines.md": { + "StatusCode": 206, + "LastSeen": "2026-03-30T15:42:04.292849-04:00" }, "https://github.com/cncf/foundation/blob/main/website-guidelines.md": { "StatusCode": 206, @@ -237,67 +241,67 @@ }, "https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.789697-04:00" + "LastSeen": "2026-03-30T15:42:06.371866-04:00" }, "https://github.com/cncf/foundation/blob/master/code-of-conduct.md": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.580775-04:00" + "LastSeen": "2026-03-30T15:42:07.468452-04:00" }, "https://github.com/cncf/foundation/blob/master/copyright-notices.md": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.954463-04:00" + "LastSeen": "2026-03-30T15:42:06.043978-04:00" }, "https://github.com/cncf/glossary": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.470017-04:00" + "LastSeen": "2026-03-30T15:42:04.451817-04:00" }, "https://github.com/cncf/project-template": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.95612-04:00" + "LastSeen": "2026-03-30T15:42:04.357533-04:00" }, "https://github.com/cncf/sandbox": { "StatusCode": 206, - "LastSeen": "2025-04-22T19:39:31.8704-04:00" + "LastSeen": "2026-03-30T15:54:06.254734-04:00" }, "https://github.com/cncf/servicedesk": { "StatusCode": 206, - "LastSeen": "2025-04-22T19:39:32.21738-04:00" + "LastSeen": "2026-03-30T15:54:06.789543-04:00" }, "https://github.com/cncf/tag-app-delivery": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.942477-04:00" + "LastSeen": "2026-03-30T15:42:07.621973-04:00" }, "https://github.com/cncf/tag-env-sustainability": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.676592-04:00" + "LastSeen": "2026-03-30T15:42:08.849948-04:00" }, "https://github.com/cncf/tag-runtime": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.337715-04:00" + "LastSeen": "2026-03-30T15:42:17.949104-04:00" }, "https://github.com/cncf/techdocs": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.275112-04:00" + "LastSeen": "2026-03-30T15:42:05.21562-04:00" }, "https://github.com/cncf/techdocs/blob/main/README.md": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.693644-04:00" + "LastSeen": "2026-03-30T15:42:10.050679-04:00" }, "https://github.com/cncf/techdocs/issues": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.599716-04:00" + "LastSeen": "2026-03-30T15:42:04.989619-04:00" }, "https://github.com/cncf/techdocs/issues/108": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.252231-04:00" + "LastSeen": "2026-03-30T15:42:06.957591-04:00" }, "https://github.com/cncf/techdocs/tree/main/analyses": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.795255-04:00" + "LastSeen": "2026-03-30T15:42:04.345559-04:00" }, "https://github.com/cncf/techdocs/tree/main/docs": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.864864-04:00" + "LastSeen": "2026-03-30T15:42:05.660632-04:00" }, "https://github.com/cncf/techdocs/tree/main/docs/README.md": { "StatusCode": 206, @@ -385,207 +389,207 @@ }, "https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.885666-04:00" + "LastSeen": "2026-03-30T15:42:05.651454-04:00" }, "https://github.com/envoyproxy/envoy/blob/main/GOVERNANCE.md": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.779403-04:00" + "LastSeen": "2026-03-30T15:42:11.372267-04:00" }, "https://github.com/etcd-io/website/pull/403": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.702767-04:00" + "LastSeen": "2026-03-30T15:42:07.944503-04:00" }, "https://github.com/helm/community": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.421105-04:00" + "LastSeen": "2026-03-30T15:42:08.988248-04:00" }, "https://github.com/hhiroshell": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.164426-04:00" + "LastSeen": "2026-03-30T15:42:08.051467-04:00" }, "https://github.com/jonasrosland": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.826771-04:00" + "LastSeen": "2026-03-30T15:42:10.181949-04:00" }, "https://github.com/kaitoii11": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.0703-04:00" + "LastSeen": "2026-03-30T15:42:06.157469-04:00" }, "https://github.com/kenta-iijima": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.574544-04:00" + "LastSeen": "2026-03-30T15:42:18.391798-04:00" }, "https://github.com/krook": { "StatusCode": 206, - "LastSeen": "2025-06-14T10:39:11.530306-04:00" + "LastSeen": "2026-03-30T15:54:06.299038-04:00" }, "https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:43.580609-04:00" + "LastSeen": "2026-03-30T15:42:13.428114-04:00" }, "https://github.com/kubernetes/website/blob/7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:44.346332-04:00" + "LastSeen": "2026-03-30T15:42:14.486692-04:00" }, "https://github.com/kubernetes/website/blob/main/hugo.toml": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.655723-04:00" + "LastSeen": "2026-03-30T15:42:05.75394-04:00" }, "https://github.com/kubernetes/website/blob/main/layouts/partials/navbar-version-selector.html": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.193851-04:00" + "LastSeen": "2026-03-30T15:42:04.868363-04:00" }, "https://github.com/longhorn/website": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.512339-04:00" + "LastSeen": "2026-03-30T15:42:06.890572-04:00" }, "https://github.com/naonishijima": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.75709-04:00" + "LastSeen": "2026-03-30T15:42:05.474373-04:00" }, "https://github.com/nate-double-u": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.185856-04:00" + "LastSeen": "2026-03-30T15:42:04.498525-04:00" }, "https://github.com/nate-double-u/technical-documentation-versioning": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.615197-04:00" + "LastSeen": "2026-03-30T15:42:07.210219-04:00" }, "https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.966203-04:00" + "LastSeen": "2026-03-30T15:42:06.212203-04:00" }, "https://github.com/nrb": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.535931-04:00" + "LastSeen": "2026-03-30T15:42:08.823263-04:00" }, "https://github.com/opentracing/opentracing.io/issues": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.018763-04:00" + "LastSeen": "2026-03-30T15:42:08.233122-04:00" }, "https://github.com/sftim": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:43.805308-04:00" + "LastSeen": "2026-03-30T15:42:13.756388-04:00" }, "https://github.com/tbatard": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.80753-04:00" + "LastSeen": "2026-03-30T15:42:07.630335-04:00" }, "https://github.com/thisisobate": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.199875-04:00" + "LastSeen": "2026-03-30T15:42:05.996396-04:00" }, "https://github.com/vitessio/website/pull/1119": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.751462-04:00" + "LastSeen": "2026-03-30T15:42:06.694925-04:00" }, "https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.43175-04:00" + "LastSeen": "2026-03-30T15:42:11.324475-04:00" }, "https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.206262-04:00" + "LastSeen": "2026-03-30T15:42:08.409221-04:00" }, "https://goharbor.io/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.657248-04:00" + "LastSeen": "2026-03-30T15:42:13.037058-04:00" }, "https://helm.sh/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.065332-04:00" + "LastSeen": "2026-03-30T15:42:12.576727-04:00" }, "https://inclusivenaming.org": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.397055-04:00" + "LastSeen": "2026-03-30T15:42:04.342304-04:00" }, "https://kubernetes.io": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:43.368612-04:00" + "LastSeen": "2026-03-30T15:42:13.503668-04:00" }, "https://kubernetes.io/docs/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.362238-04:00" + "LastSeen": "2026-03-30T15:42:05.343069-04:00" }, "https://kubernetes.io/ja/docs/contribute/localization/#style-guide": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.933919-04:00" + "LastSeen": "2026-03-30T15:42:03.476847-04:00" }, "https://lunrjs.com/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.138198-04:00" + "LastSeen": "2026-03-30T15:42:04.679563-04:00" }, "https://prometheus.io/community/": { - "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.51314-04:00" + "StatusCode": 200, + "LastSeen": "2026-03-30T15:42:07.210126-04:00" }, "https://prometheus.io/docs": { - "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.57018-04:00" + "StatusCode": 200, + "LastSeen": "2026-03-30T15:42:04.092013-04:00" }, "https://servicedesk.cncf.io": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:40.355292-04:00" + "LastSeen": "2026-03-30T15:42:06.388194-04:00" }, "https://servicedesk.cncf.io/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:39.39085-04:00" + "LastSeen": "2026-03-30T15:42:04.134716-04:00" }, "https://slack.cncf.io": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:43.836734-04:00" + "LastSeen": "2026-03-30T15:42:20.296404-04:00" }, "https://support.google.com/analytics/answer/10089681": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:39.160574-04:00" + "LastSeen": "2026-03-30T15:42:04.053319-04:00" }, "https://support.google.com/analytics/answer/10220869": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:43.011475-04:00" + "LastSeen": "2026-03-30T15:42:08.125383-04:00" }, "https://support.google.com/analytics/answer/10268458": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:42.671721-04:00" + "LastSeen": "2026-03-30T15:42:07.546836-04:00" }, "https://support.google.com/analytics/answer/10759417": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:41.212361-04:00" + "LastSeen": "2026-03-30T15:42:06.104141-04:00" }, "https://support.google.com/analytics/answer/11583528": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:38.647647-04:00" + "LastSeen": "2026-03-30T15:42:03.316022-04:00" }, "https://support.google.com/analytics/answer/9973999": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:44.228594-04:00" + "LastSeen": "2026-03-30T15:42:09.619873-04:00" }, "https://support.linuxfoundation.org/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:42.307171-04:00" + "LastSeen": "2026-03-30T15:42:06.419752-04:00" }, "https://technical-documentation-versioning.netlify.app/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.032013-04:00" + "LastSeen": "2026-03-30T15:42:06.461006-04:00" }, "https://thanos.io/tip/contributing/how-to-contribute-to-docs.md": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:40.391896-04:00" + "LastSeen": "2026-03-30T15:42:06.907337-04:00" }, "https://tockify.com/cncf.public.events/monthly": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:39.549384-04:00" + "LastSeen": "2026-03-30T15:42:03.99942-04:00" }, "https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/": { - "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:39.488425-04:00" + "StatusCode": 206, + "LastSeen": "2026-03-30T15:42:07.507568-04:00" }, "https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:39.399607-04:00" + "LastSeen": "2026-03-30T15:42:05.695522-04:00" }, "https://velero.io/": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.584554-04:00" + "LastSeen": "2026-03-30T15:42:03.711888-04:00" }, "https://www.apache.org/licenses/LICENSE-2.0": { "StatusCode": 206, @@ -593,50 +597,50 @@ }, "https://www.cncf.io/project-metrics": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:38.392657-04:00" + "LastSeen": "2026-03-30T15:42:03.722801-04:00" }, "https://www.cncf.io/wp-content/themes/cncf-twenty-two/images/favicon.ico": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.164465-04:00" + "LastSeen": "2026-03-30T15:42:03.220005-04:00" }, "https://www.docsy.dev": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.471331-04:00" + "LastSeen": "2026-03-30T15:42:04.342318-04:00" }, - "https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics": { + "https://www.docsy.dev/docs/content/feedback/#adding-analytics": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.700718-04:00" + "LastSeen": "2026-03-30T15:50:23.907648-04:00" }, "https://www.fluentd.org/testimonials": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:42.498739-04:00" + "LastSeen": "2026-03-30T15:42:12.835994-04:00" }, "https://www.git-scm.com/book/en/v2/Git-Tools-Submodules": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:41.942795-04:00" + "LastSeen": "2026-03-30T15:42:11.842922-04:00" }, "https://www.linuxfoundation.org/legal/privacy-policy": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:38.777636-04:00" + "LastSeen": "2026-03-30T15:42:03.931341-04:00" }, "https://www.linuxfoundation.org/legal/trademark-usage": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:39.262344-04:00" + "LastSeen": "2026-03-30T15:42:04.41037-04:00" }, "https://www.linuxfoundation.org/trademark-usage/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:40.189267-04:00" + "LastSeen": "2026-03-30T15:42:06.84379-04:00" }, "https://www.lios.ca/en/blogue/concept-task-reference/": { "StatusCode": 200, - "LastSeen": "2025-03-19T11:52:39.320251-04:00" + "LastSeen": "2026-03-30T15:42:04.193466-04:00" }, "https://www.rfc-editor.org/rfc/rfc2119": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:38.675317-04:00" + "LastSeen": "2026-03-30T15:42:03.825892-04:00" }, "https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872": { "StatusCode": 206, - "LastSeen": "2025-03-19T11:52:39.706039-04:00" + "LastSeen": "2026-03-30T15:42:03.487723-04:00" } } From 818fbd5da9257df74fba1301329286610aef7928 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 30 Mar 2026 19:17:40 -0700 Subject: [PATCH 093/104] Formatting fixes to build Signed-off-by: Bruce Hamilton --- docs/analytics/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/analytics/index.md b/docs/analytics/index.md index 6783971..a1f52ac 100644 --- a/docs/analytics/index.md +++ b/docs/analytics/index.md @@ -12,8 +12,7 @@ title: Analytics Google Analytics account. The first step is to make projects@cncf.io and Administrator of their existing GA account. - Request the creation of a new analytics property. -- For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your - [Docsy][]-based website, see Adding Analytics. +- For instructions on how to set up Google Analytics 4 (GA4) for your [Docsy]-based website, see Adding Analytics. > **Archived instructions**: for details on how to migrate from Universal > Analytics to GA4, see From a254030ab38b9cbc396c609102b7d80592482ba1 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 30 Mar 2026 19:28:10 -0700 Subject: [PATCH 094/104] Minimal formatting fixes Signed-off-by: Bruce Hamilton --- docs/analytics/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/analytics/index.md b/docs/analytics/index.md index d8b28d9..f776829 100644 --- a/docs/analytics/index.md +++ b/docs/analytics/index.md @@ -12,14 +12,14 @@ title: Analytics Google Analytics account. The first step is to make projects@cncf.io and Administrator of their existing GA account. - Request the creation of a new analytics property. -- For instructions on how to set up Google Analytics 4 (GA4) for your [Docsy]-based website, see Adding Analytics. +- For instructions on how to set up Google Analytics 4 (GA4) + for your [Docsy]-based website, see Adding Analytics. > **Archived instructions**: for details on how to migrate from Universal > Analytics to GA4, see > [Migrating Universal to Google Analytics 4](ua-to-ga4.md). -[adding analytics]: - https://www.docsy.dev/docs/content/feedback/#adding-analytics +[Adding analytics](https://www.docsy.dev/docs/content/feedback/#adding-analytics) [CNCF sandbox]: https://github.com/cncf/sandbox [docsy]: https://www.docsy.dev [ga4]: https://support.google.com/analytics/answer/10089681 From a2216546241384c39a5b73b5d969085e96ce425e Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 30 Mar 2026 19:33:22 -0700 Subject: [PATCH 095/104] Ran VS Code Prittier extension on index.md Signed-off-by: Bruce Hamilton --- docs/analytics/index.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/analytics/index.md b/docs/analytics/index.md index f776829..db73fd5 100644 --- a/docs/analytics/index.md +++ b/docs/analytics/index.md @@ -12,15 +12,14 @@ title: Analytics Google Analytics account. The first step is to make projects@cncf.io and Administrator of their existing GA account. - Request the creation of a new analytics property. -- For instructions on how to set up Google Analytics 4 (GA4) - for your [Docsy]-based website, see Adding Analytics. +- For instructions on how to set up Google Analytics 4 (GA4) for your + [Docsy]-based website, see Adding Analytics. > **Archived instructions**: for details on how to migrate from Universal > Analytics to GA4, see > [Migrating Universal to Google Analytics 4](ua-to-ga4.md). [Adding analytics](https://www.docsy.dev/docs/content/feedback/#adding-analytics) -[CNCF sandbox]: https://github.com/cncf/sandbox -[docsy]: https://www.docsy.dev -[ga4]: https://support.google.com/analytics/answer/10089681 -[service desk]: https://github.com/cncf/servicedesk +[CNCF sandbox]: https://github.com/cncf/sandbox [docsy]: https://www.docsy.dev +[ga4]: https://support.google.com/analytics/answer/10089681 [service desk]: +https://github.com/cncf/servicedesk From 376a69c2e2348bc7f1c5ef74a0a54307e8e339e2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 30 Mar 2026 20:14:48 -0700 Subject: [PATCH 096/104] minimal format fixes to index.md Signed-off-by: Bruce Hamilton --- docs/analytics/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/analytics/index.md b/docs/analytics/index.md index db73fd5..e909246 100644 --- a/docs/analytics/index.md +++ b/docs/analytics/index.md @@ -6,8 +6,8 @@ title: Analytics ## Google Analytics -- [CNCF sandbox][] projects currently onboarding, should open a [Service Desk][] - ticket to either: +- CNCF sandbox projects currently onboarding, should open a Service Desk ticket + to either: - Request a transfer of their existing GA properties to the **CNCF Projects** Google Analytics account. The first step is to make projects@cncf.io and Administrator of their existing GA account. From 9c1d952e6d37773c3cea6fac72a8fd12afb41305 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 31 Mar 2026 09:09:55 -0700 Subject: [PATCH 097/104] Restore docs/analytics/index.md from upstream/main Signed-off-by: Bruce Hamilton --- docs/analytics/index.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/analytics/index.md b/docs/analytics/index.md index e909246..d90c6f8 100644 --- a/docs/analytics/index.md +++ b/docs/analytics/index.md @@ -6,20 +6,22 @@ title: Analytics ## Google Analytics -- CNCF sandbox projects currently onboarding, should open a Service Desk ticket - to either: +- [CNCF sandbox][] projects currently onboarding, should open a [Service Desk][] + ticket to either: - Request a transfer of their existing GA properties to the **CNCF Projects** Google Analytics account. The first step is to make projects@cncf.io and Administrator of their existing GA account. - Request the creation of a new analytics property. -- For instructions on how to set up Google Analytics 4 (GA4) for your - [Docsy]-based website, see Adding Analytics. +- For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your + [Docsy][]-based website, see [Adding Analytics][]. > **Archived instructions**: for details on how to migrate from Universal > Analytics to GA4, see > [Migrating Universal to Google Analytics 4](ua-to-ga4.md). -[Adding analytics](https://www.docsy.dev/docs/content/feedback/#adding-analytics) -[CNCF sandbox]: https://github.com/cncf/sandbox [docsy]: https://www.docsy.dev -[ga4]: https://support.google.com/analytics/answer/10089681 [service desk]: -https://github.com/cncf/servicedesk +[adding analytics]: + https://www.docsy.dev/docs/content/feedback/#adding-analytics +[CNCF sandbox]: https://github.com/cncf/sandbox +[docsy]: https://www.docsy.dev +[ga4]: https://support.google.com/analytics/answer/10089681 +[service desk]: https://github.com/cncf/servicedesk From 4780366c593434383315b106dcfe142b16c97ef8 Mon Sep 17 00:00:00 2001 From: Nate W Date: Tue, 31 Mar 2026 09:58:35 -0700 Subject: [PATCH 098/104] Apply suggestion from @chalin Co-authored-by: Patrice Chalin Signed-off-by: Nate W --- analyses/2026/flatcar/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index bb17b92..9a8a76e 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -2,7 +2,7 @@ title: Flatcar Documentation Analysis tags: [Flatcar] created: 2026-02-26 -modified: 2026-02-26 +modified: 2026-02-31 author: Bruce Hamilton (@iRaindrop) --- From 93fdf4ffe8e3ca084ddc38ac0e4fa98ab0e37a03 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 31 Mar 2026 10:21:56 -0700 Subject: [PATCH 099/104] put back remaining part of template Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 306 ++++++++++++++++++++++++++++++ 1 file changed, 306 insertions(+) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 9a8a76e..2a9640a 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -383,3 +383,309 @@ sophistication where such verbiage would be suspicious. #### Content creation processes #### Inclusive language + +## Contributor documentation + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +_PROJECT_ is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +_PROJECT_ is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria] professional-quality documentation alongside +the project code. + +| Criterion | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | [rating (1-5)] | +| Beginner friendly issue backlog | [rating (1-5)] | +| “New contributor” getting started content | [rating (1-5)] | +| Project governance documentation | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Contributor Documentation +> here. + +The following sections contain brief assessments of each element of the +Contributor Documentation rubric. + +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the contributor documentation might +> be contained in the documentation repository. (Criteria are copied from +> criteria.md) + +#### Communication methods documented + +One of the easiest ways to attract new contributors is making sure they know how +to reach you. + +We evaluate on the following: + +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked + from your website? +- Is there a direct link to your GitHub organization/repository? +- Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings? +- Are mailing lists documented? + +#### Beginner friendly issue backlog + +We evaluate on the following: + +- Are docs issues well-triaged? +- Is there a clearly marked way for new contributors to make code or + documentation contributions (i.e. a “good first issue” label)? +- Are issues well-documented (i.e., more than just a title)? +- Are issues maintained for staleness? + +#### New contributor getting started content + +Open source is complex and projects have many processes to manage that. Are +processes easy to understand and written down so that new contributors can jump +in easily? + +We evaluate on the following: + +- Do you have a community repository or section on your website? +- Is there a document specifically for new contributors/your first contribution? +- Do new users know where to get help? + +#### Project governance documentation + +One of the CNCF’s core project values is open governance. + +We evaluate on the following: + +- Is project governance clearly documented? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Communication methods documented + +#### Beginner friendly issue backlog + +#### New contributor getting started content + +#### Project governance documentation + +## Website and infrastructure + +> AUTHOR NOTE: Pick the CNCF maturity level of the project: + +_PROJECT_ is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria] standards for documentation. + +> AUTHOR NOTE: or + +_PROJECT_ is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria] professional-quality documentation alongside +the project code. + +| Criterion | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | [rating (1-5)] | +| Meets min website req. (for maturity level) | [rating (1-5)] | +| Usability, accessibility, and design | [rating (1-5)] | +| Branding and design | [rating (1-5)] | +| Case studies/social proof | [rating (1-5)] | +| SEO, Analytics, and site-local search | [rating (1-5)] | +| Maintenance planning | [rating (1-5)] | +| A11y plan & implementation | [rating (1-5)] | +| Mobile-first plan & impl. | [rating (1-5)] | +| HTTPS access & HTTP redirect | [rating (1-5)] | +| Google Analytics 4 for production only | [rating (1-5)] | +| Indexing allowed for production server only | [rating (1-5)] | +| Intra-site / local search | [rating (1-5)] | +| Account custodians are documented | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Website and documentation +> infrastructure here. + +The following sections contain brief assessments of each element of the Website +and documentation infrastructure rubric. + +> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the website infrastructure criteria +> depend on the tools (static site generator, website framework and hosting, +> analytics tools, etc.) and processes (project CI, release procedures, +> governance, etc.) used to produce the documentation. (Criteria are copied from +> criteria.md) + +#### Single-source requirement + +Source files for _all website pages_ should reside in a single repo. Among other +problems, keeping source files in two places: + +- confuses contributors +- requires you to keep two sources in sync +- increases the likelihood of errors +- 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][git-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. + +#### Minimal website requirements + +Listed here are the minimal website requirements for projects based on their +[maturity level][maturity-level], either incubating or graduated. (These are the +only two levels for which a tech docs analysis can be requested.) + + + +| Criterion | Incubating Requirement | Graduated Requirement | +| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | +| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + + + +[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[maturity-level]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[cncf-servicedesk]: https://servicedesk.cncf.io + +#### Usability, accessibility and devices + +Most CNCF websites are accessed from mobile and other non-desktop devices at +least 10-20% of the time. Planning for this early in your website's design will +be much less effort than retrofitting a desktop-first design. + +- Is the website usable from mobile? +- Are doc pages readable? +- Are all / most website features accessible from mobile -- such as the top-nav, + site search and in-page table of contents? +- Might a [mobile-first] design make sense for your project? + +[mobile-first]: + https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first + +Plan for suitable [accessibility][] measures for your website. For example: + +- Are color contrasts significant enough for color-impaired readers? +- Are most website features usable using a keyboard only? +- Does text-to-speech offer listeners a good experience? + +It is up to each project to set their own guidelines. + +[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility + +#### Branding and design + +CNCF seeks to support enterprise-ready open source software. A key aspect of +this is branding and marketing. + +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? + +#### Case studies/social proof + +One of the best ways to advertise an open source project is to show other +organizations using it. + +We evaluate on the following: + +- Are there case studies available for the project and are they documented on + the website? +- Are there user testimonials available? +- Is there an active project blog? +- Are there community talks for the project and are they present on the website? +- Is there a logo wall of users/participating organizations? + +#### 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. + +We evaluate on the following: + +- Analytics: + - Is analytics enabled for the production server? + - Is analytics disabled for all other deploys? + - If your project used Google Analytics, have you migrated to GA4? + - Can Page-not-found (404) reports easily be generated from you site + analytics? Provide a sample of the site's current top-10 404s. +- Is site indexing supported for the production server, while disabled for + website previews and builds for non-default branches? +- Is local intra-site search available from the website? +- Are the current custodian(s) of the following accounts clearly documented: + analytics, Google Search Console, site-search (such as Google CSE or Algolia) + +#### Maintenance planning + +Website maintenance is an important part of project success, especially when +project maintainers aren’t web developers. + +We evaluate on the following: + +- Is your website tooling well supported by the community (i.e., Hugo with the + Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) +- Are you actively cultivating website maintainers from within the community? +- Are site build times reasonable? +- Do site maintainers have adequate permissions? + +#### Other + +- Is your website accessible via HTTPS? +- Does HTTP access, if any, redirect to HTTPS? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Single-source requirement + +#### Minimal website requirements + +#### Usability, accessibility and devices + +#### Branding and design + +#### Case studies/social proof + +#### SEO, Analytics and site-local search + +#### Maintenance planning + +#### Other + +#### References and notes + +##### Rating values + +The numeric rating values used in this document are as follows + +1. Not present +2. Needs improvement +3. Meets standards +4. Meets or exceeds standards +5. Exemplary + +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues-list.md +[project-website]: _PROJECT-WEBSITE_ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md + From 88af8e1193c53cb9544582c67495fa61756a9aa0 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 31 Mar 2026 11:13:27 -0700 Subject: [PATCH 100/104] Fixed prittier hits Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 39 +++++++++++-------------------- 1 file changed, 13 insertions(+), 26 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 2a9640a..4a1d87c 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -386,15 +386,8 @@ sophistication where such verbiage would be suspicious. ## Contributor documentation -> AUTHOR NOTE: Pick the CNCF maturity level of the project: - -_PROJECT_ is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -_PROJECT_ is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside +Flatcar is an **incubating** project of CNCF. This means that the project +should be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | @@ -431,7 +424,7 @@ We evaluate on the following: join those meetings? - Are mailing lists documented? -#### Beginner friendly issue backlog +#### Beginner-friendly issue backlog We evaluate on the following: @@ -468,7 +461,7 @@ We evaluate on the following: #### Communication methods documented -#### Beginner friendly issue backlog +#### Beginner-friendly issue backlog #### New contributor getting started content @@ -478,13 +471,8 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -_PROJECT_ is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria] standards for documentation. - -> AUTHOR NOTE: or - -_PROJECT_ is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria] professional-quality documentation alongside +Flatcar is an **incubating** project of CNCF. This means that the project +should be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | @@ -497,11 +485,11 @@ the project code. | SEO, Analytics, and site-local search | [rating (1-5)] | | Maintenance planning | [rating (1-5)] | | A11y plan & implementation | [rating (1-5)] | -| Mobile-first plan & impl. | [rating (1-5)] | +| Mobile-first plan & implementation | [rating (1-5)] | | HTTPS access & HTTP redirect | [rating (1-5)] | | Google Analytics 4 for production only | [rating (1-5)] | | Indexing allowed for production server only | [rating (1-5)] | -| Intra-site / local search | [rating (1-5)] | +| Within site / local search | [rating (1-5)] | | Account custodians are documented | [rating (1-5)] | ### Comments @@ -549,7 +537,7 @@ only two levels for which a tech docs analysis can be requested.) | [Website guidelines] | All guidelines satisfied | All guidelines satisfied | | **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | | **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | -| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: hosting | Hosted directly | All Hosted directly | | **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | @@ -594,7 +582,7 @@ 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? +- The website’s typography clean and well-suited for reading? #### Case studies/social proof @@ -612,7 +600,7 @@ We evaluate on the following: #### SEO, Analytics and site-local search -SEO helps users find your project and it's documentation, and analytics helps +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. @@ -622,7 +610,7 @@ We evaluate on the following: - Is analytics enabled for the production server? - Is analytics disabled for all other deploys? - If your project used Google Analytics, have you migrated to GA4? - - Can Page-not-found (404) reports easily be generated from you site + - Can Page-not-found (404) reports easily be generated from your site analytics? Provide a sample of the site's current top-10 404s. - Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? @@ -637,7 +625,7 @@ project maintainers aren’t web developers. We evaluate on the following: -- Is your website tooling well supported by the community (i.e., Hugo with the +- Is your website tooling well-supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) - Are you actively cultivating website maintainers from within the community? - Are site build times reasonable? @@ -688,4 +676,3 @@ The numeric rating values used in this document are as follows [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md - From b5d289a0e9dd830e1e52e0c7386e2da99275b6d9 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 31 Mar 2026 11:20:04 -0700 Subject: [PATCH 101/104] Prittier VS Code ext - Format Document test Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 4a1d87c..0da2180 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -386,9 +386,8 @@ sophistication where such verbiage would be suspicious. ## Contributor documentation -Flatcar is an **incubating** project of CNCF. This means that the project -should be developing professional-quality documentation alongside -the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should +be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | @@ -471,9 +470,8 @@ We evaluate on the following: > AUTHOR NOTE: Pick the CNCF maturity level of the project: -Flatcar is an **incubating** project of CNCF. This means that the project -should be developing professional-quality documentation alongside -the project code. +Flatcar is an **incubating** project of CNCF. This means that the project should +be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ------------------------------------------- | -------------- | From 7fb416b08b208f4259347e0ba000fdfb18a279b2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 31 Mar 2026 18:33:39 -0700 Subject: [PATCH 102/104] Update analyses/2026/flatcar/analysis.md Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 0da2180..0e94a6b 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -10,7 +10,7 @@ author: Bruce Hamilton (@iRaindrop) ## Introduction -This document is an analysis the effectiveness and completeness of the +This document is an analysis of the effectiveness and completeness of the [Flatcar](https://www.flatcar.org/docs/latest) open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native From 18bfd4f0574485607890b635685f5800d46d580b Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 31 Mar 2026 18:34:07 -0700 Subject: [PATCH 103/104] Update analyses/2026/flatcar/analysis.md Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 0e94a6b..adec303 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -25,7 +25,7 @@ efforts. This document was written to analyze the current state of Flatcar documentation. It aims to provide project leaders with an informed understanding of potential -problems in current project documentation. A second **implementation** document, +problems in current project documentation. A second **implementation** document outlines an actionable plan for improvement. A third document is an **issues list** of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. From 9f64df357a254ab60d0fdd4110e47667ef6ba6ea Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 31 Mar 2026 18:45:31 -0700 Subject: [PATCH 104/104] Update analyses/2026/flatcar/analysis.md Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index adec303..df01dc7 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -54,8 +54,7 @@ The site's code is stored on the Flatcar GitHub repo. #### Out of scope -Other Flatcar besides the flatcar-website: -https://github.com/flatcar/flatcar-website. +Other Flatcar documentation besides the flatcar-website. ### How this document is organized