Flatcar documentation analysis by iRaindrop · Pull Request #339 · cncf/techdocs

iRaindrop · 2026-02-27T05:39:15Z

Added template and started customizing

netlify · 2026-02-27T05:39:19Z

✅ Deploy Preview for cncf-techdocs ready!

Name	Link
🔨 Latest commit	`9f64df3`
🔍 Latest deploy log	https://app.netlify.com/projects/cncf-techdocs/deploys/69cc78bee93faf0008e4d2fe
😎 Deploy Preview	https://deploy-preview-339--cncf-techdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

chalin

The Docsy links have been fixed. Please undo the changes to the pages under docs, and then rebase your PR or to a merge update. (A rebase would be better.) /cc @nate-double-u

* updating domain and netlify information Signed-off-by: Nate W <natew@cncf.io> * Update docs/services.md Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io> --------- Signed-off-by: Nate W <natew@cncf.io> Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

* adding guidance for Series LLCs Signed-off-by: Nate W <natew@cncf.io> * Update docs/website-guidelines-checklist.md Signed-off-by: Nate W <natew@cncf.io> * Update docs/website-guidelines-checklist.md Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io> * updating formatting after applying edit Signed-off-by: Nate W <natew@cncf.io> --------- Signed-off-by: Nate W <natew@cncf.io> Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Updating Nate W.'s role. Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

* Revise README, update PC role, add links Signed-off-by: Patrice Chalin <pchalin@gmail.com> * Nate's feedback Signed-off-by: Patrice Chalin <pchalin@gmail.com> --------- Signed-off-by: Patrice Chalin <pchalin@gmail.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

* Add Vitess analysis document. Signed-off-by: Dave Welsch <dwelsch@expertsupport.com> * renaming file Signed-off-by: Nate W <natew@cncf.io> * fixing formatting issues Signed-off-by: Nate W <natew@cncf.io> * fixing formatting issues Signed-off-by: Nate W <natew@cncf.io> * Update per review comments, including recommendations for FAQ and troubleshooting. Signed-off-by: Dave Welsch <dwelsch@expertsupport.com> * Update analyses/0014-vitess/analysis.md Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io> * Update analyses/0014-vitess/analysis.md Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io> * removing SEO, Analytics and local search sections as out of scope for this analyis. Signed-off-by: Nate W <natew@cncf.io> * updating spelling wordlist Signed-off-by: Nate W <natew@cncf.io> * fixing format Signed-off-by: Nate W <natew@cncf.io> * removing markdown disable no-bare-urls Signed-off-by: Nate W <natew@cncf.io> * updating codefence formatting Signed-off-by: Nate W <natew@cncf.io> * disabling fence-code-langage check on quoted content Signed-off-by: Nate W <natew@cncf.io> * fixing formatting Signed-off-by: Nate W <natew@cncf.io> --------- Signed-off-by: Dave Welsch <dwelsch@expertsupport.com> Signed-off-by: Nate W <natew@cncf.io> Co-authored-by: Nate W <natew@cncf.io> Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

…ncf#312) Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

* adding Daniel to staff list Signed-off-by: Nate W <natew@cncf.io> * formatting and spelling Signed-off-by: Nate W <natew@cncf.io> --------- Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: Dave Welsch <dwelsch@expertsupport.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: thisisobate <obasiuche62@gmail.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

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 <bhamilton@expertsupport.com>

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

…nalysis' into bhamilton-flatcar-analysis

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

docs/analytics/index.md

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

chalin

LGTM in that all checks are passing an no docs pages are being edited via this PR anymore.

@nate-double-u has agreed to do a final review before this gets merged.

analyses/2026/flatcar/analysis.md

chalin · 2026-03-31T16:33:58Z

analyses/2026/flatcar/analysis.md

+| 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)] |


Should the ratings be set for each table-entry row?

Yes, still to do - thx

nate-double-u · 2026-03-31T16:56:51Z

Would you like me to clean up the commits @iRaindrop (ie, do a rebase)? You'd likely have to check out the PR again if you're working locally on your machine. Let me know.

Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io>

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

nate-double-u · 2026-03-31T22:07:55Z

Would you like me to clean up the commits @iRaindrop (ie, do a rebase)? You'd likely have to check out the PR again if you're working locally on your machine. Let me know.

Actually, since this is still a draft, let's leave it alone. We can squash later.

analyses/2026/flatcar/analysis.md

dwelsch-esi · 2026-03-31T21:06:45Z

analyses/2026/flatcar/analysis.md

+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".


Which static site generator, theme, and platform?

analyses/2026/flatcar/analysis.md

dwelsch-esi · 2026-03-31T21:11:48Z

analyses/2026/flatcar/analysis.md

+- Contributor documentation
+- Website and documentation infrastructure


Link to the other two sections as well.

dwelsch-esi · 2026-04-01T00:20:52Z

analyses/2026/flatcar/analysis.md

+- **Does your code release process account for documentation creation &
+  updates?**
+
+Supported, but not a formalized process at this time.


Can you be more specific about what "supported" means here?

dwelsch-esi · 2026-04-01T00:22:49Z

analyses/2026/flatcar/analysis.md

+
+- **Who reviews and approves documentation pull requests?**
+
+Team members are determined.


Can you be specific about who "team members" are and what "determines" them?

"Maintainers approve documentation pull requests."
or
"Maintainers delegate doc approval to experienced code contributors."
or ...?

dwelsch-esi · 2026-04-01T00:23:02Z

analyses/2026/flatcar/analysis.md

+
+- **Does the website have a clear owner/maintainer?**
+
+Team members are determined.


dwelsch-esi · 2026-04-01T00:28:18Z

analyses/2026/flatcar/analysis.md

+The 175 hits were "master", "disable", "abort", and "man in the middle". Of
+those only "abort" would necessitate a fix on eight occurrences.


What does "necessitate" mean here? Is it a tier-1 term?

175 is a lot of hits.

Also, if a significant number of those require extra time and effort to remedy (if they're variable names in the API, for example), note that.

Their word list don't always recommend changing, as for "disable"
https://inclusivenaming.org/word-lists/no-change/disable/index.html

They do recommend replacing "master", but when "master" is the name of the repository, like "main", it can't be replaced as used in the contributor documentation.

Man in the middle is "consider replacement"
https://inclusivenaming.org/word-lists/tier-3/man-in-middle/index.html

The hits are in my Google sheet, which most of you have access to, or let me know if you don't. Its on the Inclusive Hits tab.

https://docs.google.com/spreadsheets/d/1SJEsvwF70GYQlK0JUU6JWslJRmMMeE8LVfL5MOR6EPU/edit?gid=1130668672#gid=1130668672

dwelsch-esi · 2026-04-01T00:33:06Z

analyses/2026/flatcar/analysis.md

+No, the complexity of the content is a given, and the content assumes a level of
+sophistication where such verbiage would be suspicious.


Complex content is no guaranteed, and I don't buy the "suspicious" claim. The intent of this criterion is to avoid potentially alienating "ableist" language.

Look for phrases like "Installation is a simple matter of running the install.sh script."

Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

iRaindrop marked this pull request as draft February 27, 2026 05:40

iRaindrop force-pushed the bhamilton-flatcar-analysis branch 2 times, most recently from df99150 to 2545994 Compare March 30, 2026 22:17

chalin requested changes Mar 30, 2026

View reviewed changes

nate-double-u and others added 25 commits March 30, 2026 18:10

Use slack.cncf.io as canonical URL (cncf#300)

5bdf293

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Docusaurus version of docs pages (cncf#301)

4771e4f

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Adjust markdown syntax of analyses pages (cncf#302)

4e04c4d

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Update README.md

fd94c4f

Updating Nate W.'s role. Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Fix licenses (cncf#305)

9dadc76

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Add links to licenses to README and site footer (cncf#306)

2e862c5

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Fix production URL (cncf#308)

0ed9ebf

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

[CI] Use htmltest for link checking (cncf#310)

6448746

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Analytics docs rework: factor out UA-to-GA4 instructions, and more (c…

214fa5c

…ncf#312) Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

adding Daniel to staff list (cncf#316)

142d44e

* adding Daniel to staff list Signed-off-by: Nate W <natew@cncf.io> * formatting and spelling Signed-off-by: Nate W <natew@cncf.io> --------- Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

removing mention of alphabetizing the staff list

e2e9841

Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Update refcache: Add Daniel's GH handle (cncf#319)

b6f41ad

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

[CI] Update packages (cncf#321)

3515b26

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

[docs] Use canonical path in link (cncf#322)

02a5e7b

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Rename {analyses,docs}/**/README.md to index.md (cncf#323)

f313240

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Fix page title, adjust link-check scripts (cncf#324)

ad5cef0

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Link, title, and filename adjustments (cncf#325)

44768a0

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Canonicalize README links, cleanup package.json (cncf#326)

9176192

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Add Knative TechDoc analysis and issues list. (cncf#329)

af88d50

Signed-off-by: Dave Welsch <dwelsch@expertsupport.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

chore: fix CI errors

23edd70

Signed-off-by: thisisobate <obasiuche62@gmail.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

chore: prettify docs

cbb8d42

Signed-off-by: thisisobate <obasiuche62@gmail.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

iRaindrop and others added 7 commits March 30, 2026 18:42

Used Prittier extension

6a19e26

Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

link edits

c999702

Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

minor edit to rebuild

9d98c0c

Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

spelling fix

5d4dad4

Signed-off-by: Bruce Hamilton <12780597+iRaindrop@users.noreply.github.com> Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

edit to rebuild

642800e

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Link edits

2375571

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

iRaindrop force-pushed the bhamilton-flatcar-analysis branch from d33f662 to c45e8c9 Compare March 31, 2026 01:44

iRaindrop and others added 6 commits March 30, 2026 18:57

Merge branch 'main' into bhamilton-flatcar-analysis

0e4ca48

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

Formatting fixes to build

818fbd5

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Merge remote-tracking branch 'refs/remotes/origin/bhamilton-flatcar-a…

f8b78e5

…nalysis' into bhamilton-flatcar-analysis

Minimal formatting fixes

a254030

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Ran VS Code Prittier extension on index.md

a221654

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

minimal format fixes to index.md

376a69c

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

iRaindrop requested a review from chalin March 31, 2026 04:07

chalin requested changes Mar 31, 2026

View reviewed changes

docs/analytics/index.md Outdated Show resolved Hide resolved

Restore docs/analytics/index.md from upstream/main

9c1d952

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

chalin approved these changes Mar 31, 2026

View reviewed changes

analyses/2026/flatcar/analysis.md Outdated Show resolved Hide resolved

Merge branch 'main' into bhamilton-flatcar-analysis

27904e4

chalin reviewed Mar 31, 2026

View reviewed changes

nate-double-u and others added 4 commits March 31, 2026 09:58

Apply suggestion from @chalin

4780366

Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io>

put back remaining part of template

93fdf4f

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Fixed prittier hits

88af8e1

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

Prittier VS Code ext - Format Document test

b5d289a

Signed-off-by: Bruce Hamilton <bhamilton@expertsupport.com>

dwelsch-esi reviewed Apr 1, 2026

View reviewed changes

iRaindrop and others added 3 commits March 31, 2026 18:33

Update analyses/2026/flatcar/analysis.md

7fb416b

Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

Update analyses/2026/flatcar/analysis.md

18bfd4f

Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

Update analyses/2026/flatcar/analysis.md

9f64df3

Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

		- Contributor documentation
		- Website and documentation infrastructure


		- Who reviews and approves documentation pull requests?

		Team members are determined.


		- Does the website have a clear owner/maintainer?

		Team members are determined.

		The 175 hits were "master", "disable", "abort", and "man in the middle". Of
		those only "abort" would necessitate a fix on eight occurrences.

		No, the complexity of the content is a given, and the content assumes a level of
		sophistication where such verbiage would be suspicious.

Conversation

iRaindrop commented Feb 27, 2026

Uh oh!

netlify bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cncf-techdocs ready!

Uh oh!

chalin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chalin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nate-double-u commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nate-double-u commented Mar 31, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

netlify bot commented Feb 27, 2026 •

edited

Loading

nate-double-u commented Mar 31, 2026 •

edited

Loading