From a39f7d76ceade49e62ffbb4e3f66ef7c2047192d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 11 Apr 2026 22:20:12 -0700 Subject: [PATCH 01/42] Contribor docs section updated Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 123 ++++++++++++++++++------------ 1 file changed, 74 insertions(+), 49 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 14597477..20e47054 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -272,29 +272,30 @@ specifically for them. We evaluate on the following: - **Is “getting started” or similar clearly labeled?** -The "Learning Series" is a well-documented getting started guide. There is a -Heading 3 heading "Getting started" in the overview. + 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. + 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, the guidance -still works but would be helped greatly with numbered steps. + Even if the new user does not know anything about the technologies, the + guidance still works but would be helped greatly with numbered steps. - **If needed, are multiple OSes documented?** -Users are typically running a Linux machine, or a Virtual Machine running on -Windows or macOS. It would be beneficial to acquaint the user with any specific -client guidance, particularly when installing tools and images. For example, -brew may not install all components one gets from directly installing binaries. + Users are typically running a Linux machine, or a Virtual Machine running on + Windows or macOS. It would be beneficial to acquaint the user with any + specific client guidance, particularly when installing tools and images. For + example, brew may not install all components one gets from directly installing + binaries. - **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. + 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?** @@ -304,8 +305,8 @@ 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. + 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 @@ -316,16 +317,16 @@ 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. + 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. + Being an incubating project, the content is not versioned at this time. ##### Content creation processes @@ -337,21 +338,21 @@ We evaluate on the following: - **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?** -The team regularly updates content as the project is incubating. + The team regularly updates content as the project is incubating. - **Who reviews and approves documentation pull requests?** -Maintainers delegate doc approval to experienced code contributors. + Maintainers delegate doc approval to experienced code contributors. - **Does the website have a clear owner/maintainer?** -Yes. + Yes. ##### Inclusive language @@ -368,9 +369,9 @@ those only "abort" would necessitate a fix on eight occurrences. - **Does the project use language like "simple", "easy", etc.?** -Yes, there are about 53 hits of "easy" to replace. The word "simple" is used, -but the context is a simpler piece of code or process rather than a task being -simple. + Yes, there are about 53 hits of "easy" to replace. The word "simple" is used, + but the context is a simpler piece of code or process rather than a task being + simple. ### Recommendations @@ -460,24 +461,16 @@ be developing 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)] | +| Communication methods documented | 3 | +| Beginner friendly issue backlog | 3 | +| “New contributor” getting started content | 3 | +| Project governance documentation | 3 | ### 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 @@ -485,22 +478,54 @@ 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? +- **Is there a Slack or similar resource and is it linked from your website?** + + Yes, however these chat and social media links are on the README file of the + [Flatcar GitHub repository](https://github.com/flatcar/Flatcar). + + Chats: + - Matrix: https://app.element.io/#/room/#flatcar:matrix.org + - Slack: https://kubernetes.slack.com/archives/C03GQ8B5XNJ Social media: + - Mastodon: https://hachyderm.io/@flatcar + - X: https://x.com/flatcar + +- **Is there a direct link to your GitHub organization/repository?** + + Not from the website. + +- **Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings?** + + Yes. Project planning, meetings, and discussions are available on the GitHub + repository: https://github.com/flatcar/Flatcar/discussions and + https://github.com/flatcar/Flatcar/discussions/2025. + - 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?** + + Yes, this URL shows doc issues being tracked in GitHub: + https://github.com/flatcar/Flatcar/issues?q=state%3Aopen%20label%3Akind%2Fdocs + +- **Is there a clearly marked way for new contributors to make code or + documentation contributions (i.e. a “good first issue” label)?** + + Each page has these two links at the bottom: + - An `Edit this page` link opens the page for editing in GitHub if a fork + exists, otherwise shows the option to fork the repository. + - A `File documentation issue` link opens a new GitHub issue. + +- **Are issues well-documented (i.e., more than just a title)?** + + Yes, most issues are thoroughly described with detailed proposed solutions. + +- **Are issues maintained for staleness?** + + Generally, yes. #### New contributor getting started content From 29dcc383e256c80e7ebf5767b66529d0561bf095 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 12 Apr 2026 18:01:25 -0700 Subject: [PATCH 02/42] more updates Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 20e47054..5968127b 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -535,9 +535,26 @@ 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?** + + Not currently. + +- **Is there a document specifically for new contributors/your first + contribution?** + + Yes. There is a "How to contribute" node at the bottom of the navigation tree, + and contains guidance on making pull requests in the Flatcar GitHub + repository. Also included is guidance style and formatting with links to style + guides. + + https://www.flatcar.org/docs/latest/contribute/ + +- **Do new users know where to get help?** + + That would be Flatcar's Slack and Matrix chat channels. That information is + available in the README for Flatcar's GitHub repository: + + https://github.com/flatcar/Flatcar?tab=readme-ov-file #### Project governance documentation From 3d18440d788f00172d10e7df816a54bd52e89fe6 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Apr 2026 12:16:32 -0700 Subject: [PATCH 03/42] more writing Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 5968127b..954d9858 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -461,10 +461,10 @@ be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | 3 | -| Beginner friendly issue backlog | 3 | -| “New contributor” getting started content | 3 | -| Project governance documentation | 3 | +| Communication methods documented | 4 | +| Beginner friendly issue backlog | 4 | +| “New contributor” getting started content | 4 | +| Project governance documentation | 4 | ### Comments @@ -500,7 +500,14 @@ We evaluate on the following: repository: https://github.com/flatcar/Flatcar/discussions and https://github.com/flatcar/Flatcar/discussions/2025. -- Are mailing lists documented? + Meeting info is also noted in the [Community Meetings](https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md#community-meetings) section of the Contribution Guidelines. + +- **Are mailing lists documented?** + + Yes, in the README of the [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) these mailing lists are noted: + + Flatcar Users: https://groups.google.com/g/flatcar-linux-user + Flatcar Devs: https://groups.google.com/g/flatcar-linux-dev #### Beginner-friendly issue backlog @@ -542,12 +549,12 @@ We evaluate on the following: - **Is there a document specifically for new contributors/your first contribution?** - Yes. There is a "How to contribute" node at the bottom of the navigation tree, + Yes. There is a [How to contribute]( https://www.flatcar.org/docs/latest/contribute/) node at the bottom of the navigation tree, and contains guidance on making pull requests in the Flatcar GitHub repository. Also included is guidance style and formatting with links to style guides. - https://www.flatcar.org/docs/latest/contribute/ + In addition to the website, there is guidance for contributors on the README page of the Flatcar GitHub repository, in [Participate and Contribute](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#participate-and-contribute) section. - **Do new users know where to get help?** @@ -562,7 +569,9 @@ 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?** + + Yes, [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) is well documented. ### Recommendations From d15b3151d12092c2a0ad4c5f98909fe97e84491a Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Apr 2026 15:53:34 -0700 Subject: [PATCH 04/42] ran prittier Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 38 +++++++++++++++++++------------ 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 954d9858..671adf75 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -461,10 +461,10 @@ be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | 4 | -| Beginner friendly issue backlog | 4 | -| “New contributor” getting started content | 4 | -| Project governance documentation | 4 | +| Communication methods documented | 4 | +| Beginner friendly issue backlog | 4 | +| “New contributor” getting started content | 4 | +| Project governance documentation | 4 | ### Comments @@ -500,14 +500,18 @@ We evaluate on the following: repository: https://github.com/flatcar/Flatcar/discussions and https://github.com/flatcar/Flatcar/discussions/2025. - Meeting info is also noted in the [Community Meetings](https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md#community-meetings) section of the Contribution Guidelines. + Meeting info is also noted in the + [Community Meetings](https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md#community-meetings) + section of the Contribution Guidelines. - **Are mailing lists documented?** - Yes, in the README of the [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) these mailing lists are noted: + Yes, in the README of the + [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) + these mailing lists are noted: - Flatcar Users: https://groups.google.com/g/flatcar-linux-user - Flatcar Devs: https://groups.google.com/g/flatcar-linux-dev + Flatcar Users: https://groups.google.com/g/flatcar-linux-user Flatcar Devs: + https://groups.google.com/g/flatcar-linux-dev #### Beginner-friendly issue backlog @@ -549,12 +553,16 @@ We evaluate on the following: - **Is there a document specifically for new contributors/your first contribution?** - Yes. There is a [How to contribute]( https://www.flatcar.org/docs/latest/contribute/) node at the bottom of the navigation tree, - and contains guidance on making pull requests in the Flatcar GitHub - repository. Also included is guidance style and formatting with links to style - guides. + Yes. There is a + [How to contribute](https://www.flatcar.org/docs/latest/contribute/) node at + the bottom of the navigation tree, and contains guidance on making pull + requests in the Flatcar GitHub repository. Also included is guidance style and + formatting with links to style guides. - In addition to the website, there is guidance for contributors on the README page of the Flatcar GitHub repository, in [Participate and Contribute](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#participate-and-contribute) section. + In addition to the website, there is guidance for contributors on the README + page of the Flatcar GitHub repository, in + [Participate and Contribute](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#participate-and-contribute) + section. - **Do new users know where to get help?** @@ -571,7 +579,9 @@ We evaluate on the following: - **Is project governance clearly documented?** - Yes, [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) is well documented. + Yes, + [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) + is well documented. ### Recommendations From 0e0c0d4ed52da8bdb93aa432305e01ebd28fb537 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Apr 2026 16:01:09 -0700 Subject: [PATCH 05/42] spelling fix 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 671adf75..2b241d92 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -510,8 +510,8 @@ We evaluate on the following: [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) these mailing lists are noted: - Flatcar Users: https://groups.google.com/g/flatcar-linux-user Flatcar Devs: - https://groups.google.com/g/flatcar-linux-dev + Flatcar Users: https://groups.google.com/g/flatcar-linux-user Flatcar + Developers: https://groups.google.com/g/flatcar-linux-dev #### Beginner-friendly issue backlog From 5a280f9cd82eff553cd03e681a24495c8e92b949 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 11 Apr 2026 22:20:12 -0700 Subject: [PATCH 06/42] Contribor docs section updated Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 123 ++++++++++++++++++------------ 1 file changed, 74 insertions(+), 49 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index a3a3120e..123eeedb 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -273,29 +273,30 @@ specifically for them. We evaluate on the following: - **Is “getting started” or similar clearly labeled?** -The "Learning Series" is a well-documented getting started guide. There is a -Heading 3 heading "Getting started" in the overview. + 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. + 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, the guidance -still works but would be helped greatly with numbered steps. + Even if the new user does not know anything about the technologies, the + guidance still works but would be helped greatly with numbered steps. - **If needed, are multiple OSes documented?** -Users are typically running a Linux machine, or a Virtual Machine running on -Windows or macOS. It would be beneficial to acquaint the user with any specific -client guidance, particularly when installing tools and images. For example, -brew may not install all components one gets from directly installing binaries. + Users are typically running a Linux machine, or a Virtual Machine running on + Windows or macOS. It would be beneficial to acquaint the user with any + specific client guidance, particularly when installing tools and images. For + example, brew may not install all components one gets from directly installing + binaries. - **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. + 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?** @@ -305,8 +306,8 @@ 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. + 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 @@ -317,16 +318,16 @@ 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. + 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. + Being an incubating project, the content is not versioned at this time. ##### Content creation processes @@ -338,21 +339,21 @@ We evaluate on the following: - **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?** -The team regularly updates content as the project is incubating. + The team regularly updates content as the project is incubating. - **Who reviews and approves documentation pull requests?** -Maintainers delegate doc approval to experienced code contributors. + Maintainers delegate doc approval to experienced code contributors. - **Does the website have a clear owner/maintainer?** -Yes. + Yes. ##### Inclusive language @@ -369,9 +370,9 @@ those only "abort" would necessitate a fix on eight occurrences. - **Does the project use language like "simple", "easy", etc.?** -Yes, there are about 53 hits of "easy" to replace. The word "simple" is used, -but the context is a simpler piece of code or process rather than a task being -simple. + Yes, there are about 53 hits of "easy" to replace. The word "simple" is used, + but the context is a simpler piece of code or process rather than a task being + simple. ### Recommendations @@ -461,24 +462,16 @@ be developing 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)] | +| Communication methods documented | 3 | +| Beginner friendly issue backlog | 3 | +| “New contributor” getting started content | 3 | +| Project governance documentation | 3 | ### 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 @@ -486,22 +479,54 @@ 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? +- **Is there a Slack or similar resource and is it linked from your website?** + + Yes, however these chat and social media links are on the README file of the + [Flatcar GitHub repository](https://github.com/flatcar/Flatcar). + + Chats: + - Matrix: https://app.element.io/#/room/#flatcar:matrix.org + - Slack: https://kubernetes.slack.com/archives/C03GQ8B5XNJ Social media: + - Mastodon: https://hachyderm.io/@flatcar + - X: https://x.com/flatcar + +- **Is there a direct link to your GitHub organization/repository?** + + Not from the website. + +- **Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings?** + + Yes. Project planning, meetings, and discussions are available on the GitHub + repository: https://github.com/flatcar/Flatcar/discussions and + https://github.com/flatcar/Flatcar/discussions/2025. + - 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?** + + Yes, this URL shows doc issues being tracked in GitHub: + https://github.com/flatcar/Flatcar/issues?q=state%3Aopen%20label%3Akind%2Fdocs + +- **Is there a clearly marked way for new contributors to make code or + documentation contributions (i.e. a “good first issue” label)?** + + Each page has these two links at the bottom: + - An `Edit this page` link opens the page for editing in GitHub if a fork + exists, otherwise shows the option to fork the repository. + - A `File documentation issue` link opens a new GitHub issue. + +- **Are issues well-documented (i.e., more than just a title)?** + + Yes, most issues are thoroughly described with detailed proposed solutions. + +- **Are issues maintained for staleness?** + + Generally, yes. #### New contributor getting started content From ea3562e7a3c0afd32ba82e9938c135cd9553a402 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 12 Apr 2026 18:01:25 -0700 Subject: [PATCH 07/42] more updates Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 123eeedb..3740e9fe 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -536,9 +536,26 @@ 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?** + + Not currently. + +- **Is there a document specifically for new contributors/your first + contribution?** + + Yes. There is a "How to contribute" node at the bottom of the navigation tree, + and contains guidance on making pull requests in the Flatcar GitHub + repository. Also included is guidance style and formatting with links to style + guides. + + https://www.flatcar.org/docs/latest/contribute/ + +- **Do new users know where to get help?** + + That would be Flatcar's Slack and Matrix chat channels. That information is + available in the README for Flatcar's GitHub repository: + + https://github.com/flatcar/Flatcar?tab=readme-ov-file #### Project governance documentation From 955347e6c98a54f2a2013215e8216f442836d971 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Apr 2026 12:16:32 -0700 Subject: [PATCH 08/42] more writing Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 3740e9fe..24749b0d 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -462,10 +462,10 @@ be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | 3 | -| Beginner friendly issue backlog | 3 | -| “New contributor” getting started content | 3 | -| Project governance documentation | 3 | +| Communication methods documented | 4 | +| Beginner friendly issue backlog | 4 | +| “New contributor” getting started content | 4 | +| Project governance documentation | 4 | ### Comments @@ -501,7 +501,14 @@ We evaluate on the following: repository: https://github.com/flatcar/Flatcar/discussions and https://github.com/flatcar/Flatcar/discussions/2025. -- Are mailing lists documented? + Meeting info is also noted in the [Community Meetings](https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md#community-meetings) section of the Contribution Guidelines. + +- **Are mailing lists documented?** + + Yes, in the README of the [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) these mailing lists are noted: + + Flatcar Users: https://groups.google.com/g/flatcar-linux-user + Flatcar Devs: https://groups.google.com/g/flatcar-linux-dev #### Beginner-friendly issue backlog @@ -543,12 +550,12 @@ We evaluate on the following: - **Is there a document specifically for new contributors/your first contribution?** - Yes. There is a "How to contribute" node at the bottom of the navigation tree, + Yes. There is a [How to contribute]( https://www.flatcar.org/docs/latest/contribute/) node at the bottom of the navigation tree, and contains guidance on making pull requests in the Flatcar GitHub repository. Also included is guidance style and formatting with links to style guides. - https://www.flatcar.org/docs/latest/contribute/ + In addition to the website, there is guidance for contributors on the README page of the Flatcar GitHub repository, in [Participate and Contribute](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#participate-and-contribute) section. - **Do new users know where to get help?** @@ -563,7 +570,9 @@ 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?** + + Yes, [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) is well documented. ### Recommendations From 62b845618dd05ff38636497283b44e1e740dfdcb Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Apr 2026 15:53:34 -0700 Subject: [PATCH 09/42] ran prittier Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 38 +++++++++++++++++++------------ 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 24749b0d..d779008a 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -462,10 +462,10 @@ be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | 4 | -| Beginner friendly issue backlog | 4 | -| “New contributor” getting started content | 4 | -| Project governance documentation | 4 | +| Communication methods documented | 4 | +| Beginner friendly issue backlog | 4 | +| “New contributor” getting started content | 4 | +| Project governance documentation | 4 | ### Comments @@ -501,14 +501,18 @@ We evaluate on the following: repository: https://github.com/flatcar/Flatcar/discussions and https://github.com/flatcar/Flatcar/discussions/2025. - Meeting info is also noted in the [Community Meetings](https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md#community-meetings) section of the Contribution Guidelines. + Meeting info is also noted in the + [Community Meetings](https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md#community-meetings) + section of the Contribution Guidelines. - **Are mailing lists documented?** - Yes, in the README of the [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) these mailing lists are noted: + Yes, in the README of the + [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) + these mailing lists are noted: - Flatcar Users: https://groups.google.com/g/flatcar-linux-user - Flatcar Devs: https://groups.google.com/g/flatcar-linux-dev + Flatcar Users: https://groups.google.com/g/flatcar-linux-user Flatcar Devs: + https://groups.google.com/g/flatcar-linux-dev #### Beginner-friendly issue backlog @@ -550,12 +554,16 @@ We evaluate on the following: - **Is there a document specifically for new contributors/your first contribution?** - Yes. There is a [How to contribute]( https://www.flatcar.org/docs/latest/contribute/) node at the bottom of the navigation tree, - and contains guidance on making pull requests in the Flatcar GitHub - repository. Also included is guidance style and formatting with links to style - guides. + Yes. There is a + [How to contribute](https://www.flatcar.org/docs/latest/contribute/) node at + the bottom of the navigation tree, and contains guidance on making pull + requests in the Flatcar GitHub repository. Also included is guidance style and + formatting with links to style guides. - In addition to the website, there is guidance for contributors on the README page of the Flatcar GitHub repository, in [Participate and Contribute](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#participate-and-contribute) section. + In addition to the website, there is guidance for contributors on the README + page of the Flatcar GitHub repository, in + [Participate and Contribute](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#participate-and-contribute) + section. - **Do new users know where to get help?** @@ -572,7 +580,9 @@ We evaluate on the following: - **Is project governance clearly documented?** - Yes, [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) is well documented. + Yes, + [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) + is well documented. ### Recommendations From 2e5f52b17ca5f69f30aed49ef269c66b9c14aa58 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Apr 2026 16:01:09 -0700 Subject: [PATCH 10/42] spelling fix 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 d779008a..a9bd5115 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -511,8 +511,8 @@ We evaluate on the following: [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) these mailing lists are noted: - Flatcar Users: https://groups.google.com/g/flatcar-linux-user Flatcar Devs: - https://groups.google.com/g/flatcar-linux-dev + Flatcar Users: https://groups.google.com/g/flatcar-linux-user Flatcar + Developers: https://groups.google.com/g/flatcar-linux-dev #### Beginner-friendly issue backlog From d383d34f6d526a566d0936453ea2a6689634a52c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 21 Apr 2026 13:14:45 -0700 Subject: [PATCH 11/42] contributor section updates Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 68 +++++++++++++++++++------------ 1 file changed, 42 insertions(+), 26 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index a9bd5115..731d0479 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -6,8 +6,7 @@ modified: 2026-04-04 author: Bruce Hamilton (@iRaindrop) --- - - + ## Introduction @@ -26,9 +25,9 @@ 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 -outlines an actionable plan for improvement. A third document is an [issues -list] of issues to be added to the project documentation repository. These +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: @@ -56,7 +55,7 @@ repository. The site's code is stored on the Flatcar GitHub repo. #### Out of scope Any Flatcar content that is not accessed by the documentation URL, -https://www.flatcar.org/docs/latest, is outside the scope of this analysis. The +https://www.flatcar.org/docs/latest,is outside the scope of this analysis. The FAQ and Blog are outside the scope, however an argument can be made to keep an up-to-date FAQ in the core documentation. @@ -89,7 +88,7 @@ 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][]. +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 @@ -477,6 +476,19 @@ Contributor Documentation rubric. One of the easiest ways to attract new contributors is making sure they know how to reach you. +The Flatcar teams cast a wide net for gathering feedback and contributions in the following areas: + +- Documentation: Guides, tutorials, API docs +- Code: New features, bug fixes, builds, CI/CD +- Community: Issue triage, answering questions on Slack/Matrix/Mailing Lists +- Flatcar Apps: Create reference implementations for running services on Flatcar +- Outreach: blog posts, talks, presentations, workshops +- Coordination: Release management, Upstream project coordination +- Events: Bug fixing days, doc writing days, devrooms, meetups, conferences +- Design: Web design, maintaining the Flatcar website + +The team provides links to aggregated GitHub issues for newcomers and advanced users to work on. + We evaluate on the following: - **Is there a Slack or similar resource and is it linked from your website?** @@ -497,13 +509,17 @@ We evaluate on the following: - **Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings?** - Yes. Project planning, meetings, and discussions are available on the GitHub - repository: https://github.com/flatcar/Flatcar/discussions and - https://github.com/flatcar/Flatcar/discussions/2025. + Yes. Office Hours are promoted and scheduled monthly. + + When: 2nd Wednesday of every month at 2:30pm UTC + Where: https://meet.flatcar.org/OfficeHours + Agenda: https://github.com/flatcar/Flatcar/discussions/categories/flatcar-office-hours - Meeting info is also noted in the - [Community Meetings](https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md#community-meetings) - section of the Contribution Guidelines. + There are also Developer Syncs. + + When: 4th Wednesday of every month at 2:30pm UTC + Where: https://meet.flatcar.org/OfficeHours + Agenda: Developer Sync Discussions - **Are mailing lists documented?** @@ -526,6 +542,10 @@ We evaluate on the following: - **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** +Label Description +good first issue Extra guidance to help you make your first contribution +help wanted Issues suitable for non-core maintainers + Each page has these two links at the bottom: - An `Edit this page` link opens the page for editing in GitHub if a fork exists, otherwise shows the option to fork the repository. @@ -567,10 +587,12 @@ We evaluate on the following: - **Do new users know where to get help?** - That would be Flatcar's Slack and Matrix chat channels. That information is - available in the README for Flatcar's GitHub repository: + That would be Flatcar's Slack and Matrix chat channels. - https://github.com/flatcar/Flatcar?tab=readme-ov-file + - Matrix (preferred): #flatcar:matrix.org + - Slack: #flatcar (Kubernetes Slack) + - GitHub Discussions: flatcar/Flatcar/discussions + - Mailing List (Users): flatcar-linux-user #### Project governance documentation @@ -786,12 +808,6 @@ We evaluate on the following: #### Other -#### Companion documents - -Separate implementation and issues-list documents are not yet available for this -analysis. Use this page's recommendations and notes as the current source for -follow-up work. - #### References and notes ##### Rating values @@ -804,10 +820,10 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -[criteria]: /docs/analysis/criteria.md -[implementation]: #companion-documents -[issues list]: #companion-documents +[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]: /docs/website-guidelines-checklist.md +[website guidelines]: ../../website-guidelines-checklist.md From 228768cda0510db4e4e14b7b5f18a8832f3b08da Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 21 Apr 2026 13:52:19 -0700 Subject: [PATCH 12/42] misc fixes Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 41 ++++++++++++++++--------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 731d0479..f21f33fd 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -476,7 +476,8 @@ Contributor Documentation rubric. One of the easiest ways to attract new contributors is making sure they know how to reach you. -The Flatcar teams cast a wide net for gathering feedback and contributions in the following areas: +The Flatcar teams cast a wide net for gathering feedback and contributions in +the following areas: - Documentation: Guides, tutorials, API docs - Code: New features, bug fixes, builds, CI/CD @@ -484,10 +485,11 @@ The Flatcar teams cast a wide net for gathering feedback and contributions in th - Flatcar Apps: Create reference implementations for running services on Flatcar - Outreach: blog posts, talks, presentations, workshops - Coordination: Release management, Upstream project coordination -- Events: Bug fixing days, doc writing days, devrooms, meetups, conferences +- Events: Bug fixing days, doc writing days, meetups, conferences - Design: Web design, maintaining the Flatcar website -The team provides links to aggregated GitHub issues for newcomers and advanced users to work on. +The team provides links to aggregated GitHub issues for newcomers and advanced +users to work on. We evaluate on the following: @@ -511,15 +513,14 @@ We evaluate on the following: Yes. Office Hours are promoted and scheduled monthly. - When: 2nd Wednesday of every month at 2:30pm UTC - Where: https://meet.flatcar.org/OfficeHours - Agenda: https://github.com/flatcar/Flatcar/discussions/categories/flatcar-office-hours + When: 2nd Wednesday of every month at 2:30pm UTC Where: + https://meet.flatcar.org/OfficeHours Agenda: + https://github.com/flatcar/Flatcar/discussions/categories/flatcar-office-hours There are also Developer Syncs. - When: 4th Wednesday of every month at 2:30pm UTC - Where: https://meet.flatcar.org/OfficeHours - Agenda: Developer Sync Discussions + When: 4th Wednesday of every month at 2:30pm UTC Where: + https://meet.flatcar.org/OfficeHours Agenda: Developer Sync Discussions - **Are mailing lists documented?** @@ -542,14 +543,14 @@ We evaluate on the following: - **Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)?** -Label Description -good first issue Extra guidance to help you make your first contribution -help wanted Issues suitable for non-core maintainers +Label Description good first issue Extra guidance to help you make your first +contribution help wanted Issues suitable for non-core maintainers - Each page has these two links at the bottom: - - An `Edit this page` link opens the page for editing in GitHub if a fork - exists, otherwise shows the option to fork the repository. - - A `File documentation issue` link opens a new GitHub issue. +Each page has these two links at the bottom: + +- An `Edit this page` link opens the page for editing in GitHub if a fork + exists, otherwise shows the option to fork the repository. +- A `File documentation issue` link opens a new GitHub issue. - **Are issues well-documented (i.e., more than just a title)?** @@ -588,11 +589,10 @@ We evaluate on the following: - **Do new users know where to get help?** That would be Flatcar's Slack and Matrix chat channels. - - Matrix (preferred): #flatcar:matrix.org - Slack: #flatcar (Kubernetes Slack) - GitHub Discussions: flatcar/Flatcar/discussions - - Mailing List (Users): flatcar-linux-user + - Mailing List (Users): #flatcar-linux-user #### Project governance documentation @@ -820,10 +820,11 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -[criteria]: ../criteria.md + From 97a0e688449c90ed5ae70dea30e23bba6d166b82 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 21 Apr 2026 15:19:41 -0700 Subject: [PATCH 13/42] spelling fix Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index f21f33fd..3a5d4d92 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -589,10 +589,10 @@ We evaluate on the following: - **Do new users know where to get help?** That would be Flatcar's Slack and Matrix chat channels. - - Matrix (preferred): #flatcar:matrix.org - - Slack: #flatcar (Kubernetes Slack) - - GitHub Discussions: flatcar/Flatcar/discussions - - Mailing List (Users): #flatcar-linux-user + - Matrix (preferred): `#flatcar:matrix.org` + - Slack: `#flatcar` (Kubernetes Slack) + - GitHub Discussions: `flatcar/Flatcar/discussions` + - Mailing List (Users): `#flatcar-linux-user` #### Project governance documentation From 25f082249d7c51e8aa84ef3d48f11e07a38ba0c0 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 21 Apr 2026 15:25:26 -0700 Subject: [PATCH 14/42] spelling fix -> Linux 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 3a5d4d92..6cfa0b72 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -592,7 +592,7 @@ We evaluate on the following: - Matrix (preferred): `#flatcar:matrix.org` - Slack: `#flatcar` (Kubernetes Slack) - GitHub Discussions: `flatcar/Flatcar/discussions` - - Mailing List (Users): `#flatcar-linux-user` + - Mailing List (Users): `#flatcar-Linux-user` #### Project governance documentation From b4bd4fd328c4b6899bed2547ac77f2a9c3610183 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Apr 2026 12:16:32 -0700 Subject: [PATCH 15/42] more writing Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 6cfa0b72..3f256f65 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -461,10 +461,10 @@ be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | 4 | -| Beginner friendly issue backlog | 4 | -| “New contributor” getting started content | 4 | -| Project governance documentation | 4 | +| Communication methods documented | 4 | +| Beginner friendly issue backlog | 4 | +| “New contributor” getting started content | 4 | +| Project governance documentation | 4 | ### Comments From ca4bf44f1ee926d9df142150654b86e8c2a6db0b Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 17 Apr 2026 15:53:34 -0700 Subject: [PATCH 16/42] ran prittier Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 3f256f65..5f1deda9 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -461,10 +461,10 @@ be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | 4 | -| Beginner friendly issue backlog | 4 | -| “New contributor” getting started content | 4 | -| Project governance documentation | 4 | +| Communication methods documented | 4 | +| Beginner friendly issue backlog | 4 | +| “New contributor” getting started content | 4 | +| Project governance documentation | 4 | ### Comments @@ -528,8 +528,8 @@ We evaluate on the following: [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) these mailing lists are noted: - Flatcar Users: https://groups.google.com/g/flatcar-linux-user Flatcar - Developers: https://groups.google.com/g/flatcar-linux-dev + Flatcar Users: https://groups.google.com/g/flatcar-linux-user + Flatcar Developers: https://groups.google.com/g/flatcar-linux-dev #### Beginner-friendly issue backlog From cb9ba3addc16ea3601d481d503b16afacf83b842 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 21 Apr 2026 16:35:30 -0700 Subject: [PATCH 17/42] format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 5f1deda9..28f64b25 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -512,24 +512,23 @@ We evaluate on the following: join those meetings?** Yes. Office Hours are promoted and scheduled monthly. - - When: 2nd Wednesday of every month at 2:30pm UTC Where: - https://meet.flatcar.org/OfficeHours Agenda: - https://github.com/flatcar/Flatcar/discussions/categories/flatcar-office-hours + - When: 2nd Wednesday of every month at 2:30pm UTC + - Where: https://meet.flatcar.org/OfficeHours + - Agenda: + https://github.com/flatcar/Flatcar/discussions/categories/flatcar-office-hours There are also Developer Syncs. - - When: 4th Wednesday of every month at 2:30pm UTC Where: - https://meet.flatcar.org/OfficeHours Agenda: Developer Sync Discussions + - When: 4th Wednesday of every month at 2:30pm UTC + - Where: https://meet.flatcar.org/OfficeHours + - Agenda: Developer Sync Discussions - **Are mailing lists documented?** Yes, in the README of the [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) these mailing lists are noted: - - Flatcar Users: https://groups.google.com/g/flatcar-linux-user - Flatcar Developers: https://groups.google.com/g/flatcar-linux-dev + - Flatcar Users: https://groups.google.com/g/flatcar-linux-user + - Flatcar Developers: https://groups.google.com/g/flatcar-linux-dev #### Beginner-friendly issue backlog From 845342d8dc52886f25857d75b7864711b93ad1ac Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 21 Apr 2026 16:49:08 -0700 Subject: [PATCH 18/42] Update analyses/2026/flatcar/analysis.md Co-authored-by: Patrice Chalin 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 28f64b25..a5c3dd5d 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -55,7 +55,7 @@ repository. The site's code is stored on the Flatcar GitHub repo. #### Out of scope Any Flatcar content that is not accessed by the documentation URL, -https://www.flatcar.org/docs/latest,is outside the scope of this analysis. The +https://www.flatcar.org/docs/latest, is outside the scope of this analysis. The FAQ and Blog are outside the scope, however an argument can be made to keep an up-to-date FAQ in the core documentation. From 5979b0b11a40dd63062babc6cb9fcc08742a9d5e Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Apr 2026 22:26:27 -0700 Subject: [PATCH 19/42] writing updates Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 98 ++++++++++++++----------------- 1 file changed, 43 insertions(+), 55 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index a5c3dd5d..68c28443 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -131,31 +131,32 @@ be developing professional-quality documentation alongside the project code. 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 current Flatcar documentation navigation structure, 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 and expectations. However, the initial structures of documentation +sets such as Flatcar reflect the understanding, passions, and motivations of the team. -The following comments regard the top-tier nodes in the current table of +The following comments are in regard to the top-tier nodes in the current table of contents: - The top "Flatcar Container Linux" page contains references and links that appear to an alternate version of the table of contents. While its good to - provide quick links, the user wonders whether the TOC node reference the same - content, or if the links in the overview are supplemental. + provide quick links, the user wonders whether the TOC node references the same + content, or if the links in the overview (right side) are supplemental. - 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 address 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 documentation recently, outlines the key steps for provisioning, + configuring, and managing Flatcar throughout the life cycle. - 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 a top node should convey the functionality rather than a product name. -- The "Setup and Operations" node casts too much of a wide net in its title. How +- The "Setup and Operations" node casts too much of a wide net in its heading. 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 @@ -170,27 +171,25 @@ contents: - 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 "Constants - and IDs" and "Supply chain security mechanisms" but the following sections - could have better placement: + and IDs" and "Supply chain security mechanisms" but these sections + could be better placed: - "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. + Reference section and would be better as a top-tier node. - The "How to Contribute" node is well-placed and has the expected content. The documentation also includes an FAQ, accessible from the top banner of the -home page. This FAQ has some content that would be prudent to verify that it's -also in the docs, such as historical context and how images are updated. +home page. This FAQ has some content that could also be in the 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, don't have a different fill background, don't have a copy button, and -the language is not indicated. +the language is not indicated. There is already a GitHub issue on this. -New users might not be sure of the context for a given block of code. Is the +In several topics, 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, such as starting a +provider? Normally this can be reinforced by the narrative, such as starting a procedure with "In the VM window, use the following command to ..." or similar guidance. @@ -204,7 +203,7 @@ the narrative again to find that step. Essentially, the pertinent areas of knowledge to install and run Flatcar have been identified and documented. They just need to be better organized. The next -step is to structure the documentation so that it meets these objectives: +task 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 @@ -230,9 +229,7 @@ and configuring Flatcar. - **Is the documentation feature complete?** - Yes, given that Flatcar is essentially an operating system and new features - and capabilities would be readily documented. Those features and areas need to - be continuously updated. + There are issues to document how to use Flatcar with particular providers and tools. - **Are there step-by-step instructions (tasks, tutorials) documented for features?** @@ -245,14 +242,13 @@ and configuring Flatcar. - **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. + Yes, there are such features identified in GitHub issues. - **Are tasks clearly named according to user goals providing a happy path for users to get their tasks accomplished?** Not currently. The content areas are established and just need to be - coordinated into a "Flatcar installation roadmap" for most user paths. + coordinated into a "Flatcar provisioning roadmap" for most user paths. - **If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ)** @@ -300,13 +296,13 @@ specifically for them. We evaluate on the following: - **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. + 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. + example blocks with copy buttons. The code is simply in a different font. There is a GitHub issue to fix this. ##### Content maintainability & site mechanics @@ -476,40 +472,33 @@ Contributor Documentation rubric. One of the easiest ways to attract new contributors is making sure they know how to reach you. -The Flatcar teams cast a wide net for gathering feedback and contributions in -the following areas: - -- Documentation: Guides, tutorials, API docs -- Code: New features, bug fixes, builds, CI/CD -- Community: Issue triage, answering questions on Slack/Matrix/Mailing Lists -- Flatcar Apps: Create reference implementations for running services on Flatcar -- Outreach: blog posts, talks, presentations, workshops -- Coordination: Release management, Upstream project coordination -- Events: Bug fixing days, doc writing days, meetups, conferences -- Design: Web design, maintaining the Flatcar website +The Flatcar team casts a wide net for gathering feedback and contributions. Their effort spans documentation, code, community platforms, Flatcar apps, blogs, presentations, workshops, bug fixing events, developer challenges, and web design workshops. The team provides links to aggregated GitHub issues for newcomers and advanced users to work on. +The team encourages users to create a Flatcar app, a reference implementation showing how to run a specific service on Flatcar, as a compelling way learn Flatcar and help the user community. + We evaluate on the following: - **Is there a Slack or similar resource and is it linked from your website?** Yes, however these chat and social media links are on the README file of the - [Flatcar GitHub repository](https://github.com/flatcar/Flatcar). + Flatcar GitHub repository: https://github.com/flatcar/Flatcar. Chats: - Matrix: https://app.element.io/#/room/#flatcar:matrix.org - - Slack: https://kubernetes.slack.com/archives/C03GQ8B5XNJ Social media: + - Slack: https://kubernetes.slack.com/archives/C03GQ8B5XNJ + + Social media: - Mastodon: https://hachyderm.io/@flatcar - X: https://x.com/flatcar - **Is there a direct link to your GitHub organization/repository?** - Not from the website. + Not from the `flatacar.org` website, but listed in the README file of the Flatcar GitHub repository. -- **Are weekly/monthly project meetings documented? Is it clear how someone can - join those meetings?** +- **Are project meetings documented? Is it clear how someone can join those meetings?** Yes. Office Hours are promoted and scheduled monthly. - When: 2nd Wednesday of every month at 2:30pm UTC @@ -524,9 +513,7 @@ We evaluate on the following: - **Are mailing lists documented?** - Yes, in the README of the - [Flatcar GitHub repository](https://github.com/flatcar/Flatcar/tree/main?tab=readme-ov-file#mailing-lists) - these mailing lists are noted: + Yes, in the README of the Flatcar GitHub repository: - Flatcar Users: https://groups.google.com/g/flatcar-linux-user - Flatcar Developers: https://groups.google.com/g/flatcar-linux-dev @@ -539,17 +526,18 @@ We evaluate on the following: Yes, this URL shows doc issues being tracked in GitHub: https://github.com/flatcar/Flatcar/issues?q=state%3Aopen%20label%3Akind%2Fdocs -- **Is there a clearly marked way for new contributors to make code or - documentation contributions (i.e. a “good first issue” label)?** +- **Is it easy for new contributors to make contributions (i.e. a “good first issue” label)?** + + The Contributing Guide, https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md, linked from the repository README file welcomes new contributors. The "Finding issues" subsection has these helpful links: -Label Description good first issue Extra guidance to help you make your first -contribution help wanted Issues suitable for non-core maintainers + - **Good first issue** - Displays pages of coding and documentation tasks marked `good first issue` in DevOps. These issues have guidance to help newcomers with the task. + - **Help wanted issues** - suitable for non-core maintainers. -Each page has these two links at the bottom: + Each documentation page has these two links at the bottom: -- An `Edit this page` link opens the page for editing in GitHub if a fork + - **Edit this page** - link the opens the page for editing in GitHub if a fork exists, otherwise shows the option to fork the repository. -- A `File documentation issue` link opens a new GitHub issue. + - **File documentation issue** - link opens a new GitHub issue. - **Are issues well-documented (i.e., more than just a title)?** @@ -603,7 +591,7 @@ We evaluate on the following: Yes, [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) - is well documented. + document projects values of openness, fairness, community, inclusivity, and participation. For an incubating project, Flatcar is laying the foundation for vigorous community participation. ### Recommendations From 253d7042a1610eb659bd6d38be399914ad4be225 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Apr 2026 22:27:48 -0700 Subject: [PATCH 20/42] ran prittier Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 74 +++++++++++++++++++------------ 1 file changed, 45 insertions(+), 29 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 68c28443..071bfdd0 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -135,10 +135,11 @@ The current Flatcar documentation navigation structure, 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 and expectations. However, the initial structures of documentation -sets such as Flatcar reflect the understanding, passions, and motivations of the team. +sets such as Flatcar reflect the understanding, passions, and motivations of the +team. -The following comments are in regard to the top-tier nodes in the current table of -contents: +The following comments are in regard to the top-tier nodes in the current table +of contents: - The top "Flatcar Container Linux" page contains references and links that appear to an alternate version of the table of contents. While its good to @@ -156,8 +157,8 @@ contents: of the docs relate to this section. - The "Nebraska" node is about updates, but a top node should convey the functionality rather than a product name. -- The "Setup and Operations" node casts too much of a wide net in its heading. How - does "setup" differ from installation? The node contains several important +- The "Setup and Operations" node casts too much of a wide net in its heading. + 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 in deploying Flatcar. @@ -171,27 +172,27 @@ contents: - 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 "Constants - and IDs" and "Supply chain security mechanisms" but these sections - could be better placed: + and IDs" and "Supply chain security mechanisms" but these sections could be + better placed: - "Integrations" could be incorporated into the Cloud Providers documentation. - "Developer Guides" contains conceptual content typically not found in a Reference section and would be better as a top-tier node. - The "How to Contribute" node is well-placed and has the expected content. The documentation also includes an FAQ, accessible from the top banner of the -home page. This FAQ has some content that could also be in the 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. +home page. This FAQ has some content that could also be in the 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, don't have a different fill background, don't have a copy button, and the language is not indicated. There is already a GitHub issue on this. -In several topics, 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 reinforced by the narrative, such as starting a -procedure with "In the VM window, use the following command to ..." or similar -guidance. +In several topics, 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 reinforced by the narrative, such as +starting a procedure with "In the VM window, use the following command to ..." +or similar guidance. In pages with code examples the narrative follows a casual and conversational flow, introducing the steps such as "First do this", show a block of code, @@ -229,7 +230,8 @@ and configuring Flatcar. - **Is the documentation feature complete?** - There are issues to document how to use Flatcar with particular providers and tools. + There are issues to document how to use Flatcar with particular providers and + tools. - **Are there step-by-step instructions (tasks, tutorials) documented for features?** @@ -302,7 +304,8 @@ specifically for them. We evaluate on the following: 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. There is a GitHub issue to fix this. + example blocks with copy buttons. The code is simply in a different font. + There is a GitHub issue to fix this. ##### Content maintainability & site mechanics @@ -472,12 +475,17 @@ Contributor Documentation rubric. One of the easiest ways to attract new contributors is making sure they know how to reach you. -The Flatcar team casts a wide net for gathering feedback and contributions. Their effort spans documentation, code, community platforms, Flatcar apps, blogs, presentations, workshops, bug fixing events, developer challenges, and web design workshops. +The Flatcar team casts a wide net for gathering feedback and contributions. +Their effort spans documentation, code, community platforms, Flatcar apps, +blogs, presentations, workshops, bug fixing events, developer challenges, and +web design workshops. The team provides links to aggregated GitHub issues for newcomers and advanced users to work on. -The team encourages users to create a Flatcar app, a reference implementation showing how to run a specific service on Flatcar, as a compelling way learn Flatcar and help the user community. +The team encourages users to create a Flatcar app, a reference implementation +showing how to run a specific service on Flatcar, as a compelling way learn +Flatcar and help the user community. We evaluate on the following: @@ -488,7 +496,7 @@ We evaluate on the following: Chats: - Matrix: https://app.element.io/#/room/#flatcar:matrix.org - - Slack: https://kubernetes.slack.com/archives/C03GQ8B5XNJ + - Slack: https://kubernetes.slack.com/archives/C03GQ8B5XNJ Social media: - Mastodon: https://hachyderm.io/@flatcar @@ -496,9 +504,11 @@ We evaluate on the following: - **Is there a direct link to your GitHub organization/repository?** - Not from the `flatacar.org` website, but listed in the README file of the Flatcar GitHub repository. + Not from the `flatacar.org` website, but listed in the README file of the + Flatcar GitHub repository. -- **Are project meetings documented? Is it clear how someone can join those meetings?** +- **Are project meetings documented? Is it clear how someone can join those + meetings?** Yes. Office Hours are promoted and scheduled monthly. - When: 2nd Wednesday of every month at 2:30pm UTC @@ -526,17 +536,21 @@ We evaluate on the following: Yes, this URL shows doc issues being tracked in GitHub: https://github.com/flatcar/Flatcar/issues?q=state%3Aopen%20label%3Akind%2Fdocs -- **Is it easy for new contributors to make contributions (i.e. a “good first issue” label)?** +- **Is it easy for new contributors to make contributions (i.e. a “good first + issue” label)?** - The Contributing Guide, https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md, linked from the repository README file welcomes new contributors. The "Finding issues" subsection has these helpful links: - - - **Good first issue** - Displays pages of coding and documentation tasks marked `good first issue` in DevOps. These issues have guidance to help newcomers with the task. + The Contributing Guide, + https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md, linked from the + repository README file welcomes new contributors. The "Finding issues" + subsection has these helpful links: + - **Good first issue** - Displays pages of coding and documentation tasks + marked `good first issue` in DevOps. These issues have guidance to help + newcomers with the task. - **Help wanted issues** - suitable for non-core maintainers. Each documentation page has these two links at the bottom: - - **Edit this page** - link the opens the page for editing in GitHub if a fork - exists, otherwise shows the option to fork the repository. + exists, otherwise shows the option to fork the repository. - **File documentation issue** - link opens a new GitHub issue. - **Are issues well-documented (i.e., more than just a title)?** @@ -591,7 +605,9 @@ We evaluate on the following: Yes, [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) - document projects values of openness, fairness, community, inclusivity, and participation. For an incubating project, Flatcar is laying the foundation for vigorous community participation. + document projects values of openness, fairness, community, inclusivity, and + participation. For an incubating project, Flatcar is laying the foundation for + vigorous community participation. ### Recommendations From 5053a27748253f2372dd52bd40b479cfcc1df5f9 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Apr 2026 22:33:12 -0700 Subject: [PATCH 21/42] spellling fix 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 071bfdd0..eca5972f 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -504,7 +504,7 @@ We evaluate on the following: - **Is there a direct link to your GitHub organization/repository?** - Not from the `flatacar.org` website, but listed in the README file of the + Not from the `Flatacar.org` website, but listed in the README file of the Flatcar GitHub repository. - **Are project meetings documented? Is it clear how someone can join those From dc4388edb26ad513b4b25ec725633a294c4d35f1 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Apr 2026 22:38:42 -0700 Subject: [PATCH 22/42] removed inclusivity as spelling error false it 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 eca5972f..ebf55a91 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -504,7 +504,7 @@ We evaluate on the following: - **Is there a direct link to your GitHub organization/repository?** - Not from the `Flatacar.org` website, but listed in the README file of the + Not from the `Flatcar.org` website, but listed in the README file of the Flatcar GitHub repository. - **Are project meetings documented? Is it clear how someone can join those @@ -605,7 +605,7 @@ We evaluate on the following: Yes, [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) - document projects values of openness, fairness, community, inclusivity, and + document projects values of openness, fairness, community and participation. For an incubating project, Flatcar is laying the foundation for vigorous community participation. From c98bc86e25385e7ff5ef9df4bf827e666161e16b Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 22 Apr 2026 22:45:16 -0700 Subject: [PATCH 23/42] ran prittier 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 ebf55a91..1b662669 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -605,9 +605,9 @@ We evaluate on the following: Yes, [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) - document projects values of openness, fairness, community and - participation. For an incubating project, Flatcar is laying the foundation for - vigorous community participation. + document projects values of openness, fairness, community and participation. + For an incubating project, Flatcar is laying the foundation for vigorous + community participation. ### Recommendations From ec18eaf45f06442aa91afbeaced12e8555c15685 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 26 Apr 2026 20:57:30 -0700 Subject: [PATCH 24/42] added issues.md Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 9 ++- analyses/2026/flatcar/issues.md | 123 ++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 2 deletions(-) create mode 100644 analyses/2026/flatcar/issues.md diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 1b662669..cb44a496 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -611,8 +611,13 @@ We evaluate on the following: ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. +The Flatcar team is off to a robust start with it Community outreach and +involvement. All the pertinent criteria has been met for an incubating project. +As the project evolves, the following recommendations should be considered: + +- Put a link to community participation portal content on the main Flatcar.org + website. +- Include direct links to documentation issues in listings. #### Communication methods documented diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md new file mode 100644 index 00000000..06148ed5 --- /dev/null +++ b/analyses/2026/flatcar/issues.md @@ -0,0 +1,123 @@ +--- +title: Flatcar Issues +tags: [Flatcar] +created: 2026-04-24 +modified: 2026-04-24 +author: Bruce Hamilton (@iRaindrop) +--- + +## Sign-off on the documentation restructure + +### Overview + +The recommended structure of this analysis happens to also reflect the Flatcar +team's own restructuring proposal. Both naturally arrive at a navigation +structure similar with other container and Kubernetes projects that follow a +natural progression: learn → provision → configure → deploy → other guides, etc. + +Flatcar differs from a typical application or library documentation set because +it's not so much installation as is its provisioning, or creating, a container +with an immutable operating system. As such the user path, or journey, +throughout the documentation is one of tailoring an efficient first boot of the +container with the desired operating system settings and capabilities. + +The recommended structure is a table of contents of just two nodes deep. While +there can be deeper nodes, only two levels is recommended and facilitates a +positive user experience by improving discoverability. With only two levels +deep, the length of the structure, from the top Getting Started to the bottom, +gets longer. + +The structure should have all top-of-mind concepts and technologies in the first +and second tiers. Some of these nodes need to be buckets to group concepts and +procedures. Strategic planning should be able to arrive at a structure where new +nodes and changes can be accommodated without re-architecting the structure. + +Here is the recommended structure: + +| Level 1 Nodes | Level 2 Nodes/topics | +| ---------------------------------- | ----------------------------- | +| Getting Started | Overview | +| | Roadmap | +| | Tutorial | +| | CoreOS Migration | +| First Boot & Provisioning | Overview | +| | Butane Config Transpiler | +| | Infrastructure as Code | +| | Image Customization | +| | OS Extensions | +| | Virtual Machines | +| Core OS Configuration | Overview | +| | Systemd & Process Management | +| | Host Configuration | +| | Networking & Remote Access | +| | Storage & File Systems | +| Security | Overview | +| | Hardening & Compliance | +| | Encryption & Storage | +| | Certificates & Authentication | +| Deployments | Overview | +| | Cloud Providers | +| | Bare Metal | +| Orchestration & Container Runtimes | Overview | +| | Managing Clusters | +| | Kubernetes | +| | Container Runtimes | +| Updates & Releases | Overview | +| | Nebraska Update Manger | +| | Managing Releases | +| Diagnostics & Fixing Issues | Overview | +| | Debugging Guide | +| Reference | Overview | +| | Integrations | +| | Constants & IDs | +| | Supply Chain | +| Developer Guides | Overview | +| | SDK | +| How to Contribute | Overview | +| | Docs Style & Formatting | + +Notes: + +The second and third nodes, "First Boot & Provisioning" and "Core OS +Configuration" are buckets of topics related to configuration and provisioning. +The difference between the two is that an argument can be made that users will +different needs and options for provisioning as well as configuring core +settings. + +An argument could be made that "Orchestration & Container Runtimes" should have +Kubernetes in the title. In that case perhaps "Kubernetes & Orchestration" would +suffice. + +Audience: All + +Type: All + +## Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +## Possible Implementation + +Related material in the current doc: + +https://www.flatcar.org/docs/latest + +Refers to the entire left-hand navigation table of contents. + +The recommended structure is available in a Google sheet, with links to the +existing content. See the Readme tab for information about using this data. This +sheet has a row for every page in the documentation, but the hierarchical +arrangement of topics under the second note is at a level of granularity beneath +the scope of the recommended restructure. As the structure evolves, the deeper +structuring should evolve. + +Use this sheet, or a sheet derived from it, to arrived at a signed-off +structure: + +https://docs.google.com/spreadsheets/d/1SJEsvwF70GYQlK0JUU6JWslJRmMMeE8LVfL5MOR6EPU/edit?usp=sharing + +Suggested changes: + +After the Flatcar team has agreed on a structure, this issue is complete. From ef847b4389c2aef6f2e2341021ad317f5abc5856 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 26 Apr 2026 21:04:21 -0700 Subject: [PATCH 25/42] url fix Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 06148ed5..267bd8cc 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -116,7 +116,7 @@ structuring should evolve. Use this sheet, or a sheet derived from it, to arrived at a signed-off structure: -https://docs.google.com/spreadsheets/d/1SJEsvwF70GYQlK0JUU6JWslJRmMMeE8LVfL5MOR6EPU/edit?usp=sharing +https://docs.google.com/spreadsheets/d/1SJEsvwF70GYQlK0JUU6JWslJRmMMeE8LVfL5MOR6EPU/edit Suggested changes: From e2513b1d75a928b30b5b46417412538e510e6cb3 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 26 Apr 2026 21:14:11 -0700 Subject: [PATCH 26/42] removed problematic link Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 267bd8cc..d4994fe1 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -116,7 +116,7 @@ structuring should evolve. Use this sheet, or a sheet derived from it, to arrived at a signed-off structure: -https://docs.google.com/spreadsheets/d/1SJEsvwF70GYQlK0JUU6JWslJRmMMeE8LVfL5MOR6EPU/edit +(link to be provided) Suggested changes: From 835fadfcdfba3c84a63bc7b44f9925dafeac73ba Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 28 Apr 2026 08:40:52 -0700 Subject: [PATCH 27/42] more issues written Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 28 ++- analyses/2026/flatcar/issues.md | 314 +++++++++++++++++++++++++++++- 2 files changed, 324 insertions(+), 18 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index cb44a496..886a442e 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -390,21 +390,15 @@ Reference and Contributor Documentation. These recommendations are designed to be malleable. - Create a Getting Started node with the following sections: - - Create an "Installation roadmap" page for users that enables them to - determine how they want to deploy containers with Flatcar. The starting - points for the discussion are whether the user comes from an on-prem or - cloud environment and many users will use both. This purpose of this page is - to provide users with a procedure for installation. - - Prerequisites regarding client operating systems including running VMs from - macOS and Windows. - - Prerequisites for the Quickstart. - - Any guidance on installing binaries directly or using programs like brew. - - Create a "Configuration and Provisioning" page that covers the YAML coding, - using Butane and employing other configurations. Link this page from the - "Installation roadmap". - - Create a "Deployment" page, covering scenarios for Kubernetes, clustering - and distributed systems. Cover on-prem and cloud. Link from the - "Installation roadmap". + - Create an "Roadmap" page for users that enables them to determine how they + want to deploy containers with Flatcar. The starting points for the + discussion are whether the user comes from an on-prem or cloud environment + and many users will use both. This purpose of this page is to provide users + with a procedure for installation. + - Prerequisites regarding client operating systems including running VMs + from macOS and Windows. + - Prerequisites for the Quickstart. + - Any guidance on installing binaries directly or using programs like brew. - For the middle functional nodes of the table of contents, devise the categories of tools, technologies, products, and terms pertinent areas for @@ -430,6 +424,10 @@ be malleable. - Add at least one architectural diagram to top overviews that depict a container, a container with Flatcar, and perhaps nodes and clusters. +- Nodes like "Virtual Machines", "Cloud Providers", and "Security Options" have + subtopics where common tasks and concepts could be discussed in the overview, + leaving the subtopics with simpler procedures and minimal repetition. + #### Content maintainability and site mechanics - Edit each procedural topic, page with code examples, into a semiformal How-to diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index d4994fe1..058ee762 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -92,13 +92,13 @@ Audience: All Type: All -## Context +### Context This issue tracks recommended changes resulting from an analysis of the Flatcar documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. -## Possible Implementation +### Possible Implementation Related material in the current doc: @@ -107,7 +107,7 @@ https://www.flatcar.org/docs/latest Refers to the entire left-hand navigation table of contents. The recommended structure is available in a Google sheet, with links to the -existing content. See the Readme tab for information about using this data. This +existing content. See the README tab for information about using this data. This sheet has a row for every page in the documentation, but the hierarchical arrangement of topics under the second note is at a level of granularity beneath the scope of the recommended restructure. As the structure evolves, the deeper @@ -121,3 +121,311 @@ structure: Suggested changes: After the Flatcar team has agreed on a structure, this issue is complete. + +## Create the NAV.YML file + +### Overview + +After the Flatcar team has signed off on the recommended structure, the website +team will probably use a NAV.YML YAML file to map the structure to the folders +and files in the repository. + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +The NAV.YML file can be constructed using data from the level-a, level-b, and +path columns in recommended structure sheet, columns D, E, and F, respectively. + +Then create a PR to add NAV.YML to the root of the Flatcar docs repository: + +https://github.com/flatcar/flatcar-website/tree/main/content/docs/latest + +## Write a Roadmap topic + +### Overview + +This topic will be a popular one as it should guide users along a path (or +journey) for knowing what to do to get a Flatcar container going according to +their purpose and needs. + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +The roadmap should be a flow-based narrative starting with the list of paths and +each path should have a checklist of prerequsites and next steps that cover +provisioning tools and deployment. + +Configuration might be too granular for this roadmap. + +The user paths include: + +- Novice user to learn and test +- Cloud only user to work with a provider +- On-prem bare metal user +- Hybrid users + +Each path should incorporate lists of needed provisioning tools such as VMs with +reference to container runtimes and orchestration. Include any pertinent notes +on configuration and deployment. + +## Create or Update Overviews for Top Nodes + +### Overview + +Update or create the Overview pages for each of the top nodes. The overview +should be brief tour of the node's content. Also update the very top +introduction page. + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +Create or update Overview.md in each top nodes in the Flatcar documentation. + +## Create Architectural Diagrams + +### Overview + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +## Add Step Numbering to Procedures + +### Overview + +Add numbering or bullets Introduce code blocks with context Summarize procedures +in Overview Set content type to How-to in metadata + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +## Add Content Type to Metadata + +### Overview + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +## Consolidate Concepts in Virtual Machines Overview + +### Overview + +The Virtual Machines node, https://www.flatcar.org/docs/latest/installing/vms/, +has a minimal overview with several complex subtopics. Each of the subtopics in +this node contain a very similar workflow that differ only by platform. To +determine the commonalities among the subtopics, you can use AI. Here is a +suggested AP prompt: "Review the subtopics in this link (link) and provide a +list of common tasks that each of the Virtual Machine topics have in common. The +aim is to make the overview page contain most of the concepts so that each of +the subtopics can be simpler How-to topics." + +Here are the common steps determined by Copilot without the details. Run the +prompt for full context. + +1. Select a Release Channel +1. Download the Appropriate VM Image +1. Verify the Image (GPG) +1. Prepare an Ignition (or Butane) Configuration +1. Create or Define the Virtual Machine +1. Boot the VM for the First Time +1. Access the Instance (SSH) +1. Optional: Automate Deployment (Terraform, CLI tools) + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +Use AI and your own research to gather key concepts and common procedures that +each of the subtopics have so that the overview contains the conceptual guidance +and common tasks that need not be repeated by the subtopics. Copilot also +offered to write the overview draft from which good ideas could be gleaned. + +## Consolidate Concepts in the Cloud Providers Overview + +### Overview + +The Cloud Providers node, https://www.flatcar.org/docs/latest/installing/cloud/, +has a minimal overview with several complex subtopics. Each of the subtopics in +this node contain a very similar workflow that differ only by platform. To +determine the commonalities among the subtopics, you can use AI. Here is a +suggested AI prompt: "Review the subtopics in this link (link) and provide a +list of common tasks that each of the Virtual Machine topics have in common. The +aim is to make the overview page contain most of the concepts so that each of +the subtopics can be simpler How-to topics." + +Repeat this prompt for the current Community Supported Platforms node, +https://www.flatcar.org/docs/latest/installing/community-platforms/, which the +Flatcar team agrees can be combined with the Cloud Providers node as proposed in +the recommended structure. + +Here are the common steps determined by Copilot without the details. Run the +prompt for full context. + +1. Choose a Flatcar Release Channel +2. Obtain or Reference the Flatcar Image +3. Prepare an Ignition (or Butane) Configuration +4. Create or Launch the Instance +5. Pass Ignition to the Instance +6. Boot and Verify the Instance +7. Access the Instance (SSH) +8. Optional: Automate Deployment + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +Use AI and your own research to gather key concepts and common procedures that +each of the subtopics have so that the overview contains the conceptual guidance +and common tasks that need not be repeated by the subtopics. Copilot also +offered to write the overview draft from which good ideas could be gleaned. + +## Consolidate Concepts in the Cloud Providers Overview + +### Overview + +The Cloud Providers node, https://www.flatcar.org/docs/latest/installing/cloud/, +has a minimal overview with several complex subtopics. Each of the subtopics in +this node contain a very similar workflow that differ only by platform. To +determine the commonalities among the subtopics, you can use AI. Here is a +suggested AI prompt: "Review the subtopics in this link (link) and provide a +list of common tasks that each of the Cloud Providers topics have in common. The +aim is to make the overview page contain most of the concepts so that each of +the subtopics can be simpler How-to topics." + +Here are the common steps determined by Copilot without the details. Run the +prompt for full context. + +1. Choose a Flatcar Release Channel +2. Obtain or Reference the Flatcar Image +3. Prepare an Ignition (or Butane) Configuration +4. Create or Launch the Instance +5. Pass Ignition to the Instance +6. Boot and Verify the Instance +7. Access the Instance (SSH) +8. Optional: Automate Deployment + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +Use AI and your own research to gather key concepts and common procedures that +each of the subtopics have so that the overview contains the conceptual guidance +and common tasks that need not be repeated by the subtopics. Copilot also +offered to write the overview draft from which good ideas could be gleaned. + +## Consolidate Concepts in the Bare Metal Overview + +### Overview + +The Cloud Providers node, +https://www.flatcar.org/docs/latest/installing/bare-metal/, has a minimal +overview with several complex subtopics. Each of the subtopics in this node +contain a very similar workflow that differ only by platform. To determine the +commonalities among the subtopics, you can use AI. Here is a suggested AI +prompt: "Review the subtopics in this link (link) and provide a list of common +tasks that each of the Bare Metal topics have in common. The aim is to make the +overview page contain most of the concepts so that each of the subtopics can be +simpler How-to topics." + +Here are the common steps determined by Copilot without the details. Run the +prompt for full context. + +1. Obtain or Prepare Flatcar Artifacts +2. Understand the Boot Flow +3. Provide an Ignition (or Butane) Configuration +4. Configure the Bootloader or Boot Environment +5. Perform the Installation (Optional but Common) +6. Hardware‑Specific Considerations +7. Validate the System After Boot + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +Use AI and your own research to gather key concepts and common procedures that +each of the subtopics have so that the overview contains the conceptual guidance +and common tasks that need not be repeated by the subtopics. Copilot also +offered to write the overview draft from which good ideas could be gleaned. + +## Consolidate Concepts in the Community Supported Platforms overview + +### Overview + +The Community Supported Platforms node, +https://www.flatcar.org/docs/latest/installing/community-platforms/, has a +minimal overview with several complex subtopics. Each of the subtopics in this +node contain a very similar workflow that differ only by platform. To determine +the commonalities among the subtopics, you can use AI. Here is a suggested AI +prompt: "Review the subtopics in this link (link) and provide a list of common +tasks that each of the Community Supported Platform topics have in common. The +aim is to make the overview page contain most of the concepts so that each of +the subtopics can be simpler How-to topics." + +Here are the common steps determined by Copilot without the details. Run the +prompt for full context. + +1. Choose the Correct Flatcar Image for the Platform +2. Provide an Ignition (or Butane) Configuration +3. Understand the Platform’s Boot Mechanism +4. Pass User Data / Metadata to the VM +5. Networking Basics +6. Validate Ignition and System State After First Boot +7. Optional: Customize or Replace the Disk Image + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +Use AI and your own research to gather key concepts and common procedures that +each of the subtopics have so that the overview contains the conceptual guidance +and common tasks that need not be repeated by the subtopics. Copilot also +offered to write the overview draft from which good ideas could be gleaned. From acb085d7ee61916c52e92a27a342a629b8381ab8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 28 Apr 2026 15:55:30 -0700 Subject: [PATCH 28/42] more updates Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 6 +++--- analyses/2026/flatcar/issues.md | 6 +++++- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 886a442e..4dabcf9a 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -424,9 +424,9 @@ be malleable. - Add at least one architectural diagram to top overviews that depict a container, a container with Flatcar, and perhaps nodes and clusters. -- Nodes like "Virtual Machines", "Cloud Providers", and "Security Options" have - subtopics where common tasks and concepts could be discussed in the overview, - leaving the subtopics with simpler procedures and minimal repetition. +- Nodes like "Virtual Machines", "Cloud Providers", have subtopics where common + tasks and concepts could be discussed in the overview, leaving the subtopics + with simpler procedures and minimal repetition. #### Content maintainability and site mechanics diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 058ee762..59ab9e2f 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -6,6 +6,8 @@ modified: 2026-04-24 author: Bruce Hamilton (@iRaindrop) --- + + ## Sign-off on the documentation restructure ### Overview @@ -162,7 +164,7 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation The roadmap should be a flow-based narrative starting with the list of paths and -each path should have a checklist of prerequsites and next steps that cover +each path should have a checklist of prerequisites and next steps that cover provisioning tools and deployment. Configuration might be too granular for this roadmap. @@ -396,6 +398,8 @@ offered to write the overview draft from which good ideas could be gleaned. ### Overview +Note: This node has just been renamed to "Virtualization Options". + The Community Supported Platforms node, https://www.flatcar.org/docs/latest/installing/community-platforms/, has a minimal overview with several complex subtopics. Each of the subtopics in this From 675eea04b3abb353b461c1ba93dada5da4bddde6 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 29 Apr 2026 14:58:44 -0700 Subject: [PATCH 29/42] issues near complete Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 176 +++++++++++++++++--------------- 1 file changed, 95 insertions(+), 81 deletions(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 59ab9e2f..e5d66888 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -2,13 +2,13 @@ title: Flatcar Issues tags: [Flatcar] created: 2026-04-24 -modified: 2026-04-24 +modified: 2026-04-29 author: Bruce Hamilton (@iRaindrop) --- -## Sign-off on the documentation restructure +## Sign-off and create the documentation restructure ### Overview @@ -21,75 +21,68 @@ Flatcar differs from a typical application or library documentation set because it's not so much installation as is its provisioning, or creating, a container with an immutable operating system. As such the user path, or journey, throughout the documentation is one of tailoring an efficient first boot of the -container with the desired operating system settings and capabilities. +container with the desired OS settings and capabilities. The recommended structure is a table of contents of just two nodes deep. While -there can be deeper nodes, only two levels is recommended and facilitates a -positive user experience by improving discoverability. With only two levels -deep, the length of the structure, from the top Getting Started to the bottom, -gets longer. +there can be deeper nodes, only two primary levels is recommended and +facilitates a positive user experience by improving discoverability. The structure should have all top-of-mind concepts and technologies in the first -and second tiers. Some of these nodes need to be buckets to group concepts and -procedures. Strategic planning should be able to arrive at a structure where new -nodes and changes can be accommodated without re-architecting the structure. +and second tiers. Some of these nodes need to be broader categories to group +concepts and procedures. Strategic planning should be able to arrive at a +structure where naming changes can be accommodated without re-architecting the +structure. -Here is the recommended structure: +Here is the recommended structure summary of the top two nodes. -| Level 1 Nodes | Level 2 Nodes/topics | +| Level A | Level B | | ---------------------------------- | ----------------------------- | +| Flatcar Container Linux | Top intro/overview | | Getting Started | Overview | | | Roadmap | -| | Tutorial | -| | CoreOS Migration | +| | Quickstart | +| | Learning Series | +| | Minecraft Flatcar Apps | | First Boot & Provisioning | Overview | | | Butane Config Transpiler | +| | Ignition | | | Infrastructure as Code | | | Image Customization | -| | OS Extensions | | | Virtual Machines | -| Core OS Configuration | Overview | +| OS Configuration | Overview | | | Systemd & Process Management | | | Host Configuration | | | Networking & Remote Access | | | Storage & File Systems | -| Security | Overview | -| | Hardening & Compliance | -| | Encryption & Storage | -| | Certificates & Authentication | +| System Extensions (Sysext) | Overview | +| | Systemext-bakery | | Deployments | Overview | | | Cloud Providers | +| | Virtualization Options | | | Bare Metal | | Orchestration & Container Runtimes | Overview | | | Managing Clusters | | | Kubernetes | | | Container Runtimes | -| Updates & Releases | Overview | -| | Nebraska Update Manger | +| Nebraska Update Manager & Releases | Overview | +| | Nebraska Update Manager | | | Managing Releases | -| Diagnostics & Fixing Issues | Overview | -| | Debugging Guide | -| Reference | Overview | +| Security | Overview | +| | Hardening & Compliance | +| | Encryption & Storage | +| | Certificates & Authentication | +| | Supply Chain | | | Integrations | | | Constants & IDs | -| | Supply Chain | +| Diagnostics & Fixing Issues | Overview | +| | Debugging Guide | +| CoreOS Migration | Overview | +| | Updating from CoreOS | | Developer Guides | Overview | | | SDK | | How to Contribute | Overview | | | Docs Style & Formatting | -Notes: - -The second and third nodes, "First Boot & Provisioning" and "Core OS -Configuration" are buckets of topics related to configuration and provisioning. -The difference between the two is that an argument can be made that users will -different needs and options for provisioning as well as configuring core -settings. - -An argument could be made that "Orchestration & Container Runtimes" should have -Kubernetes in the title. In that case perhaps "Kubernetes & Orchestration" would -suffice. - Audience: All Type: All @@ -108,44 +101,30 @@ https://www.flatcar.org/docs/latest Refers to the entire left-hand navigation table of contents. -The recommended structure is available in a Google sheet, with links to the -existing content. See the README tab for information about using this data. This -sheet has a row for every page in the documentation, but the hierarchical -arrangement of topics under the second note is at a level of granularity beneath -the scope of the recommended restructure. As the structure evolves, the deeper -structuring should evolve. - -Use this sheet, or a sheet derived from it, to arrived at a signed-off -structure: - -(link to be provided) - -Suggested changes: - -After the Flatcar team has agreed on a structure, this issue is complete. +The recommended detailed and summary structures are available in this +spreadsheet: -## Create the NAV.YML file +(link) -### Overview +The detailed sheet has a row for each of the current files in the repository. +The files under node level 2 are not listed in the summary sheet. These +recommended structure does not map the hierarchical sequence of these files on +the website and is assumed there will be churn in this granularity. As the +structure evolves, the deeper structuring should also evolve. -After the Flatcar team has signed off on the recommended structure, the website -team will probably use a NAV.YML YAML file to map the structure to the folders -and files in the repository. +At this writing, there is initial approval of the recommended structure and +after a final approval from the team the structure would be ready to +incorporate. A repository restructure is preferred over using a mapping file +like Nav.yaml. -### Context +The sheet has columns of `old path` and `new path`. The team needs to determine +the names of the directories that correspond to the names of the nodes, e.g. the +"First Boot & Provisioning" could have 'provisioning' as the name of the +directory (folder). -This issue tracks recommended changes resulting from an analysis of the Flatcar -documentation commissioned by CNCF. The analysis and supporting documents are -here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. - -### Possible Implementation - -The NAV.YML file can be constructed using data from the level-a, level-b, and -path columns in recommended structure sheet, columns D, E, and F, respectively. - -Then create a PR to add NAV.YML to the root of the Flatcar docs repository: - -https://github.com/flatcar/flatcar-website/tree/main/content/docs/latest +After approval from the team, a bash script could be coded from the values of +`old path` and `new path` with the `git mv` command to create the new +repository. ## Write a Roadmap topic @@ -164,11 +143,9 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation The roadmap should be a flow-based narrative starting with the list of paths and -each path should have a checklist of prerequisites and next steps that cover +each path should have a checklist of prerequisites and high-level steps that cover provisioning tools and deployment. -Configuration might be too granular for this roadmap. - The user paths include: - Novice user to learn and test @@ -184,7 +161,7 @@ on configuration and deployment. ### Overview -Update or create the Overview pages for each of the top nodes. The overview +Update or create the overview pages for each of the top two tiers of nodes. The overview should be brief tour of the node's content. Also update the very top introduction page. @@ -196,12 +173,14 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Create or update Overview.md in each top nodes in the Flatcar documentation. +Create or update Overview.md in each top nodes in the Flatcar documentation. If the node contains several subtopics you can use AI to glean content for an effective overview. See [Consolidate Concepts in Virtual Machines Overview](#consolidate-concepts-in-virtual-machines-overview) issue for an example. ## Create Architectural Diagrams ### Overview +An architectural flow diagram will optimize the documentation. At least one is needed for the top page and others where appliable and helpful. + ### Context This issue tracks recommended changes resulting from an analysis of the Flatcar @@ -210,12 +189,21 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -## Add Step Numbering to Procedures +The writer should propose a diagram when the architectural and technical flow is understood for a subject area or precise process. Use Mermaid Chart to create the Mermaid code that renders on the web and in Visual Studio Code. + +Prompt AI with a description of the flow to create the code that you can refine in Mermaid Chart. + +## Add Step Numbering and Context to Procedures ### Overview -Add numbering or bullets Introduce code blocks with context Summarize procedures -in Overview Set content type to How-to in metadata +Add numbering or bullets to introduce code blocks with context of where the code is run. + +The Flatcar team already has an issue to add code block capabilities with a copy button. When this is in place, you can add Markdown fencing syntax with the language in all pages with code. + +Currently few if any of the procedural how-to topics have numbered steps. While in some cases the casual tone is appreciated, it detracts from being able to reference exact steps and users expect numbering. Use bullets for one or two-step procedures. + +New users may be confused as to where a particular code block is run. Is it on the client machine, in a VM, in a CLI? So introduce code blocks with verbiage such as "In the VM window in a container, run the following command...". No need to do it for every block if it's obvious. ### Context @@ -225,10 +213,18 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -## Add Content Type to Metadata +Make these change every time you edit a page with code. + +## Add Content Type and make other updates to metadata ### Overview +The current metadata at the top of Flatcar Markdown files has values for `title`, `linktitle`, and `weight`. + +Adding a `content-type` or `type` value to the metadata will be great for managing the repository and achieving consistency in the content. + +Apparently the `weight` value is no longer of benefit for the team and there's discussion of removing it. + ### Context This issue tracks recommended changes resulting from an analysis of the Flatcar @@ -237,6 +233,24 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation +After the restructured repository has stabilized, a Python or other script could walk the repository and update each Markdown file's metadata. + +## Add indexing file to repository to assist AI agents + +The CTO of CNCF just suggested that all CNCF doc maintainers run a 'sanity check' with this tool that measures how well AI agents can read, navigate, and use a documentation site using this tool:  https://afdocs.dev/ + +One of the main ways to improve AI capabilities is by creating a `llms.txt` file to reside at the root of the repository that contains links to key sections, essentially a high level index. AI agents look for this file to navigate the site. + +### Context + +This issue tracks recommended changes resulting from an analysis of the Flatcar +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. + +### Possible Implementation + +Visit https://llmstxt.org to learn about the `llms.txt` file. Consult with the Flatcar team to determine key sections and check in the file. + ## Consolidate Concepts in Virtual Machines Overview ### Overview @@ -398,7 +412,7 @@ offered to write the overview draft from which good ideas could be gleaned. ### Overview -Note: This node has just been renamed to "Virtualization Options". +Note: This node will be renamed to "Virtualization Options". The Community Supported Platforms node, https://www.flatcar.org/docs/latest/installing/community-platforms/, has a From 03f3ee6fd8c90213a253e300c99980f2275b5e3d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 29 Apr 2026 15:09:56 -0700 Subject: [PATCH 30/42] spelling and prittier fixes Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 69 +++++++++++++++++++++++---------- 1 file changed, 48 insertions(+), 21 deletions(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index e5d66888..2ac44625 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -54,8 +54,8 @@ Here is the recommended structure summary of the top two nodes. | | Host Configuration | | | Networking & Remote Access | | | Storage & File Systems | -| System Extensions (Sysext) | Overview | -| | Systemext-bakery | +| System Extensions (SYSEXT) | Overview | +| | Ready to Use Extensions | | Deployments | Overview | | | Cloud Providers | | | Virtualization Options | @@ -143,8 +143,8 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation The roadmap should be a flow-based narrative starting with the list of paths and -each path should have a checklist of prerequisites and high-level steps that cover -provisioning tools and deployment. +each path should have a checklist of prerequisites and high-level steps that +cover provisioning tools and deployment. The user paths include: @@ -161,8 +161,8 @@ on configuration and deployment. ### Overview -Update or create the overview pages for each of the top two tiers of nodes. The overview -should be brief tour of the node's content. Also update the very top +Update or create the overview pages for each of the top two tiers of nodes. The +overview should be brief tour of the node's content. Also update the very top introduction page. ### Context @@ -173,13 +173,18 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Create or update Overview.md in each top nodes in the Flatcar documentation. If the node contains several subtopics you can use AI to glean content for an effective overview. See [Consolidate Concepts in Virtual Machines Overview](#consolidate-concepts-in-virtual-machines-overview) issue for an example. +Create or update Overview.md in each top nodes in the Flatcar documentation. If +the node contains several subtopics you can use AI to glean content for an +effective overview. See +[Consolidate Concepts in Virtual Machines Overview](#consolidate-concepts-in-virtual-machines-overview) +issue for an example. ## Create Architectural Diagrams ### Overview -An architectural flow diagram will optimize the documentation. At least one is needed for the top page and others where appliable and helpful. +An architectural flow diagram will optimize the documentation. At least one is +needed for the top page and others where applicable and helpful. ### Context @@ -189,21 +194,33 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -The writer should propose a diagram when the architectural and technical flow is understood for a subject area or precise process. Use Mermaid Chart to create the Mermaid code that renders on the web and in Visual Studio Code. +The writer should propose a diagram when the architectural and technical flow is +understood for a subject area or precise process. Use Mermaid Chart to create +the Mermaid code that renders on the web and in Visual Studio Code. -Prompt AI with a description of the flow to create the code that you can refine in Mermaid Chart. +Prompt AI with a description of the flow to create the code that you can refine +in Mermaid Chart. ## Add Step Numbering and Context to Procedures ### Overview -Add numbering or bullets to introduce code blocks with context of where the code is run. +Add numbering or bullets to introduce code blocks with context of where the code +is run. -The Flatcar team already has an issue to add code block capabilities with a copy button. When this is in place, you can add Markdown fencing syntax with the language in all pages with code. +The Flatcar team already has an issue to add code block capabilities with a copy +button. When this is in place, you can add Markdown fencing syntax with the +language in all pages with code. -Currently few if any of the procedural how-to topics have numbered steps. While in some cases the casual tone is appreciated, it detracts from being able to reference exact steps and users expect numbering. Use bullets for one or two-step procedures. +Currently few if any of the procedural how-to topics have numbered steps. While +in some cases the casual tone is appreciated, it detracts from being able to +reference exact steps and users expect numbering. Use bullets for one or +two-step procedures. -New users may be confused as to where a particular code block is run. Is it on the client machine, in a VM, in a CLI? So introduce code blocks with verbiage such as "In the VM window in a container, run the following command...". No need to do it for every block if it's obvious. +New users may be confused as to where a particular code block is run. Is it on +the client machine, in a VM, in a CLI? So introduce code blocks with verbiage +such as "In the VM window in a container, run the following command...". No need +to do it for every block if it's obvious. ### Context @@ -219,11 +236,14 @@ Make these change every time you edit a page with code. ### Overview -The current metadata at the top of Flatcar Markdown files has values for `title`, `linktitle`, and `weight`. +The current metadata at the top of Flatcar Markdown files has values for +`title`, `link title`, and `weight`. -Adding a `content-type` or `type` value to the metadata will be great for managing the repository and achieving consistency in the content. +Adding a `content-type` or `type` value to the metadata will be great for +managing the repository and achieving consistency in the content. -Apparently the `weight` value is no longer of benefit for the team and there's discussion of removing it. +Apparently the `weight` value is no longer of benefit for the team and there's +discussion of removing it. ### Context @@ -233,13 +253,19 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -After the restructured repository has stabilized, a Python or other script could walk the repository and update each Markdown file's metadata. +After the restructured repository has stabilized, a Python or other script could +walk the repository and update each Markdown file's metadata. ## Add indexing file to repository to assist AI agents -The CTO of CNCF just suggested that all CNCF doc maintainers run a 'sanity check' with this tool that measures how well AI agents can read, navigate, and use a documentation site using this tool:  https://afdocs.dev/ +The CTO of CNCF just suggested that all CNCF doc maintainers run a 'sanity +check' with this tool that measures how well AI agents can read, navigate, and +use a documentation site using this tool: https://afdocs.dev/ -One of the main ways to improve AI capabilities is by creating a `llms.txt` file to reside at the root of the repository that contains links to key sections, essentially a high level index. AI agents look for this file to navigate the site. +One of the main ways to improve AI capabilities is by creating a `LLMS.TXT` file +to reside at the root of the repository that contains links to key sections, +essentially a high level index. AI agents look for this file to navigate the +site. ### Context @@ -249,7 +275,8 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Visit https://llmstxt.org to learn about the `llms.txt` file. Consult with the Flatcar team to determine key sections and check in the file. +Visit https://llmstxt.org to learn about the `LLMS.TXT` file. Consult with the +Flatcar team to determine key sections and check in the file. ## Consolidate Concepts in Virtual Machines Overview From 76118c5ee3306c3e121c541d7d21ecf10651ef08 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 29 Apr 2026 15:24:19 -0700 Subject: [PATCH 31/42] false positive spelling fix Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 2ac44625..b451fd82 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -54,7 +54,7 @@ Here is the recommended structure summary of the top two nodes. | | Host Configuration | | | Networking & Remote Access | | | Storage & File Systems | -| System Extensions (SYSEXT) | Overview | +| System Extensions | Overview | | | Ready to Use Extensions | | Deployments | Overview | | | Cloud Providers | @@ -262,7 +262,7 @@ The CTO of CNCF just suggested that all CNCF doc maintainers run a 'sanity check' with this tool that measures how well AI agents can read, navigate, and use a documentation site using this tool: https://afdocs.dev/ -One of the main ways to improve AI capabilities is by creating a `LLMS.TXT` file +One of the main ways to improve AI capabilities is by creating a "llms.txt" file to reside at the root of the repository that contains links to key sections, essentially a high level index. AI agents look for this file to navigate the site. @@ -275,7 +275,7 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Visit https://llmstxt.org to learn about the `LLMS.TXT` file. Consult with the +Visit https://llmstxt.org to learn about the file. Consult with the Flatcar team to determine key sections and check in the file. ## Consolidate Concepts in Virtual Machines Overview From 4f54a154e64f05230565bea627462b78bdb3c8ec Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 29 Apr 2026 15:30:58 -0700 Subject: [PATCH 32/42] misc fixes Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index b451fd82..e27f0242 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -262,8 +262,8 @@ The CTO of CNCF just suggested that all CNCF doc maintainers run a 'sanity check' with this tool that measures how well AI agents can read, navigate, and use a documentation site using this tool: https://afdocs.dev/ -One of the main ways to improve AI capabilities is by creating a "llms.txt" file -to reside at the root of the repository that contains links to key sections, +One of the main ways to improve AI capabilities is by creating an index file to +reside at the root of the repository that contains links to key sections, essentially a high level index. AI agents look for this file to navigate the site. @@ -275,7 +275,7 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Visit https://llmstxt.org to learn about the file. Consult with the +Visit https://llmstxt.org to learn about the index file. Consult with the Flatcar team to determine key sections and check in the file. ## Consolidate Concepts in Virtual Machines Overview From 542ba6f17fdf143849239fe21e7ffba1c43b739c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 29 Apr 2026 15:36:54 -0700 Subject: [PATCH 33/42] removed duplidated section Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 43 --------------------------------- 1 file changed, 43 deletions(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index e27f0242..0d718836 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -320,49 +320,6 @@ offered to write the overview draft from which good ideas could be gleaned. ### Overview -The Cloud Providers node, https://www.flatcar.org/docs/latest/installing/cloud/, -has a minimal overview with several complex subtopics. Each of the subtopics in -this node contain a very similar workflow that differ only by platform. To -determine the commonalities among the subtopics, you can use AI. Here is a -suggested AI prompt: "Review the subtopics in this link (link) and provide a -list of common tasks that each of the Virtual Machine topics have in common. The -aim is to make the overview page contain most of the concepts so that each of -the subtopics can be simpler How-to topics." - -Repeat this prompt for the current Community Supported Platforms node, -https://www.flatcar.org/docs/latest/installing/community-platforms/, which the -Flatcar team agrees can be combined with the Cloud Providers node as proposed in -the recommended structure. - -Here are the common steps determined by Copilot without the details. Run the -prompt for full context. - -1. Choose a Flatcar Release Channel -2. Obtain or Reference the Flatcar Image -3. Prepare an Ignition (or Butane) Configuration -4. Create or Launch the Instance -5. Pass Ignition to the Instance -6. Boot and Verify the Instance -7. Access the Instance (SSH) -8. Optional: Automate Deployment - -### Context - -This issue tracks recommended changes resulting from an analysis of the Flatcar -documentation commissioned by CNCF. The analysis and supporting documents are -here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. - -### Possible Implementation - -Use AI and your own research to gather key concepts and common procedures that -each of the subtopics have so that the overview contains the conceptual guidance -and common tasks that need not be repeated by the subtopics. Copilot also -offered to write the overview draft from which good ideas could be gleaned. - -## Consolidate Concepts in the Cloud Providers Overview - -### Overview - The Cloud Providers node, https://www.flatcar.org/docs/latest/installing/cloud/, has a minimal overview with several complex subtopics. Each of the subtopics in this node contain a very similar workflow that differ only by platform. To From 03544295b537b21bbbee9e3138d1840f0df2cd39 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Apr 2026 17:59:32 -0700 Subject: [PATCH 34/42] 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 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 4dabcf9a..d14168c9 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -131,11 +131,11 @@ be developing professional-quality documentation alongside the project code. The following sections contain brief assessments of each element of the project documentation. -The current Flatcar documentation navigation structure, 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 +The current Flatcar documentation navigation structure, the *table of contents* (TOC), +defines the areas of knowledge needed to install and provision Flatcar, but it +does not show the different paths for new users depending on their environment and expectations. However, the initial structures of documentation -sets such as Flatcar reflect the understanding, passions, and motivations of the +sets such as Flatcar reflect the understanding and motivations of the team. The following comments are in regard to the top-tier nodes in the current table From 916cacfd8f3b06ee96c3028702d747bfa5502e83 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Apr 2026 17:59:54 -0700 Subject: [PATCH 35/42] 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 d14168c9..992a0aef 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -142,7 +142,7 @@ The following comments are in regard to the top-tier nodes in the current table of contents: - The top "Flatcar Container Linux" page contains references and links that - appear to an alternate version of the table of contents. While its good to + appear to refer to an alternate version of the table of contents. While its good to provide quick links, the user wonders whether the TOC node references the same content, or if the links in the overview (right side) are supplemental. - The "Installing" node contains the large "Cloud Providers" node, that might be From 3bce5a203c1209573d89f84db07434a1449afacf Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Apr 2026 18:00:20 -0700 Subject: [PATCH 36/42] 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 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 992a0aef..9022f0d7 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -145,10 +145,10 @@ of contents: appear to refer to an alternate version of the table of contents. While its good to provide quick links, the user wonders whether the TOC node references the same content, or if the links in the overview (right side) are supplemental. -- 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 "Installing" node contains the large "Cloud Providers" node, which might be +better as top tier node. The same with "Bare Metal". The team agrees that +"Community supported platforms" could be merged into the "Cloud Providers" +node. - The installation node should address 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 provisioning, From f15ee31526380283844f09f1ffef3a7cb9e28c8b Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Apr 2026 18:01:05 -0700 Subject: [PATCH 37/42] 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 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 9022f0d7..c2873589 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -157,9 +157,9 @@ node. of the docs relate to this section. - The "Nebraska" node is about updates, but a top node should convey the functionality rather than a product name. -- The "Setup and Operations" node casts too much of a wide net in its heading. +- The "Setup and Operations" node casts too wide a net in its heading. How does "setup" differ from installation? The node contains several important - content areas that should be more discoverable, for instance: +content areas that should be more discoverable. For instance: - "Managing Clusters" might be better at a higher level because it's an initial evaluation in deploying Flatcar. - The Storage and Security nodes are typically at a higher level. From 5ff92c620a8af1950035d1d3a505873a223735a2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Apr 2026 18:02:14 -0700 Subject: [PATCH 38/42] Update analyses/2026/flatcar/issues.md Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 0d718836..28d346d6 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -282,14 +282,9 @@ Flatcar team to determine key sections and check in the file. ### Overview -The Virtual Machines node, https://www.flatcar.org/docs/latest/installing/vms/, +The Virtual Machines topic, https://www.flatcar.org/docs/latest/installing/vms/, has a minimal overview with several complex subtopics. Each of the subtopics in -this node contain a very similar workflow that differ only by platform. To -determine the commonalities among the subtopics, you can use AI. Here is a -suggested AP prompt: "Review the subtopics in this link (link) and provide a -list of common tasks that each of the Virtual Machine topics have in common. The -aim is to make the overview page contain most of the concepts so that each of -the subtopics can be simpler How-to topics." +this topic contain a similar workflow that differ only by platform. Here are the common steps determined by Copilot without the details. Run the prompt for full context. From ec95c52975a93e1f9467c4fecdb0488bb3d7fba6 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Apr 2026 18:03:08 -0700 Subject: [PATCH 39/42] Update analyses/2026/flatcar/issues.md Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 28d346d6..90ebbc0f 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -286,8 +286,7 @@ The Virtual Machines topic, https://www.flatcar.org/docs/latest/installing/vms/, has a minimal overview with several complex subtopics. Each of the subtopics in this topic contain a similar workflow that differ only by platform. -Here are the common steps determined by Copilot without the details. Run the -prompt for full context. +Here are the common steps determined by Copilot without the details. 1. Select a Release Channel 1. Download the Appropriate VM Image From c3638b1d8ce51b0e9f73e675b70e5cffc6b7b15d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Apr 2026 18:20:47 -0700 Subject: [PATCH 40/42] format fixes 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 c2873589..e379a8f3 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-04-04 +modified: 2026-04-30 author: Bruce Hamilton (@iRaindrop) --- @@ -131,24 +131,24 @@ be developing professional-quality documentation alongside the project code. The following sections contain brief assessments of each element of the project documentation. -The current Flatcar documentation navigation structure, the *table of contents* (TOC), -defines the areas of knowledge needed to install and provision Flatcar, but it -does not show the different paths for new users depending on their +The current Flatcar documentation navigation structure, the _table of contents_ +(TOC), defines the areas of knowledge needed to install and provision Flatcar, +but it does not show the different paths for new users depending on their environment and expectations. However, the initial structures of documentation -sets such as Flatcar reflect the understanding and motivations of the -team. +sets such as Flatcar reflect the understanding and motivations of the team. The following comments are in regard to the top-tier nodes in the current table of contents: - The top "Flatcar Container Linux" page contains references and links that - appear to refer to an alternate version of the table of contents. While its good to - provide quick links, the user wonders whether the TOC node references the same - content, or if the links in the overview (right side) are supplemental. -- The "Installing" node contains the large "Cloud Providers" node, which might be -better as top tier node. The same with "Bare Metal". The team agrees that -"Community supported platforms" could be merged into the "Cloud Providers" -node. + appear to refer to an alternate version of the table of contents. While its + good to provide quick links, the user wonders whether the TOC node references + the same content, or if the links in the overview (right side) are + supplemental. +- The "Installing" node contains the large "Cloud Providers" node, which might + be better as top tier node. The same with "Bare Metal". The team agrees that + "Community supported platforms" could be merged into the "Cloud Providers" + node. - The installation node should address 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 provisioning, @@ -157,9 +157,9 @@ node. of the docs relate to this section. - The "Nebraska" node is about updates, but a top node should convey the functionality rather than a product name. -- The "Setup and Operations" node casts too wide a net in its heading. - How does "setup" differ from installation? The node contains several important -content areas that should be more discoverable. For instance: +- The "Setup and Operations" node casts too wide a net in its heading. 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 in deploying Flatcar. - The Storage and Security nodes are typically at a higher level. From 81ad304e7afe52f744cd1d4bc3b34640ee469e19 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Thu, 30 Apr 2026 22:02:17 -0700 Subject: [PATCH 41/42] Made Dave's suggestions in analysis.md Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 185 ++++++++++++++++-------------- analyses/2026/flatcar/issues.md | 6 +- 2 files changed, 100 insertions(+), 91 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index e379a8f3..62d7f345 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -118,13 +118,13 @@ to legal requirements such as copyright and licensing issues. 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)] | -| -------------------------- | -------------- | -| Information architecture | 3 | -| New user content | 3 | -| Content maintainability | 3 | -| Content creation processes | 4 | -| Inclusive language | 4 | +| Criterion | [Rating (1-5)] | +| -------------------------------------------------------- | -------------- | +| Information architecture meets expectations | 3 | +| New user content meets expectations | 3 | +| Content maintainability meets expectations | 3 | +| Content creation processes meets or exceeds expectations | 3 | +| Inclusive language meets or exceeds expectations | 4 | ### Comments @@ -134,17 +134,15 @@ documentation. The current Flatcar documentation navigation structure, the _table of contents_ (TOC), defines the areas of knowledge needed to install and provision Flatcar, but it does not show the different paths for new users depending on their -environment and expectations. However, the initial structures of documentation -sets such as Flatcar reflect the understanding and motivations of the team. +environment and expectations. The following comments are in regard to the top-tier nodes in the current table of contents: - The top "Flatcar Container Linux" page contains references and links that - appear to refer to an alternate version of the table of contents. While its - good to provide quick links, the user wonders whether the TOC node references - the same content, or if the links in the overview (right side) are - supplemental. + appear to refer to an alternate version of the TOC. While its good to provide + quick links, the user wonders whether the TOC node references the same + content, or if the links in the overview (right side) are supplemental. - The "Installing" node contains the large "Cloud Providers" node, which might be better as top tier node. The same with "Bare Metal". The team agrees that "Community supported platforms" could be merged into the "Cloud Providers" @@ -184,34 +182,33 @@ home page. This FAQ has some content that could also be in the 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 +Code blocks are different from those in other documentation sets as they are not bordered, don't have a different fill background, don't have a copy button, and the language is not indicated. There is already a GitHub issue on this. In several topics, 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 +of code. Is the Linux prompt on a VM, in a client computer, or in a CLI session with a cloud provider? Normally this can be reinforced by the narrative, such as starting a procedure with "In the VM window, use the following command to ..." or similar guidance. -In pages with code examples the narrative follows a casual and conversational -flow, introducing the steps such as "First do this", show a block of code, -followed by "Now do this", followed by the next block of code. While at first -this tone may seem refreshing from sterile nature of technical documentation, it -inhibits learning because it inhibits scanning and the ability to reference the -exact steps. It's easier to go back a numbered step in a procedure that to read -the narrative again to find that step. +In pages with code examples the narrative follows a conversational flow, +introducing the steps such as "First do this", show a block of code, followed by +"Now do this", followed by the next block of code. While at first this tone may +seem refreshing from sterile nature of technical documentation, it inhibits +learning because it inhibits scanning and the ability to reference the exact +steps. It's easier to go back a numbered step in a procedure that to read the +narrative again to find that step. -Essentially, the pertinent areas of knowledge to install and run Flatcar have -been identified and documented. They just need to be better organized. The next -task is to structure the documentation so that it meets these objectives: +The pertinent areas of knowledge to install and run Flatcar have been identified +and documented. They just need to be better organized. The next task 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 so that users can - identify a pathway for learning about and deploying Flatcar efficiently and - optimally. + identify a pathway for learning about and deploying Flatcar efficiently. - The structure provides effective navigation and identification of the tools and technologies so that users can identify the ones they need to learn about and use. @@ -224,22 +221,21 @@ documentation. We evaluate on the following: ##### 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. +understanding the processes and technologies involved. Now the objective is to +organize the concepts to map to the user the path for provisioning and +configuring Flatcar. - **Is the documentation feature complete?** - There are issues to document how to use Flatcar with particular providers and - tools. + There are GitHub issues to document how to use Flatcar with particular + providers and tools. - **Are there step-by-step instructions (tasks, tutorials) documented for features?** Procedures, mainly invoking bash commands, are introduced informally and do not follow the typical style of numbered steps that read "Use the following - command to ..." verbiage. It would be easy to rewrite for meet that - conformity. + command to ..." verbiage that would clarify the context. - **Are there any key features which are documented but missing task documentation?** @@ -249,13 +245,14 @@ and configuring Flatcar. - **Are tasks clearly named according to user goals providing a happy path for users to get their tasks accomplished?** - Not currently. The content areas are established and just need to be - coordinated into a "Flatcar provisioning roadmap" for most user paths. + Not currently. The content areas are established but should be coordinated + into a "Flatcar provisioning roadmap" for most user paths. - **If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ)** - The current FAQ does not provide this information. + The FAQ does not currently provide that guidance. Flatcar users of the GitHub + Flatcar repository can find help and community support in the README file. - **If the product exposes an API, is there a complete reference?** @@ -291,14 +288,14 @@ specifically for them. We evaluate on the following: - **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. + The Learning Series section 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. + Other than being a top level node in the TOC, no. - **Is there sample code or other example content that can easily be copy-pasted?** @@ -325,7 +322,7 @@ We evaluate on the following: - **Do you have a clearly documented method for versioning your content?** - Being an incubating project, the content is not versioned at this time. +Being an incubating project, the content is not versioned at this time. ##### Content creation processes @@ -337,13 +334,13 @@ We evaluate on the following: - **Is there a clearly documented (ongoing) contribution process for documentation?** - Yes. There is a 'How to contribute' node with guidance for using the GitHub + Yes. There is a 'How to contribute' section with guidance for using the GitHub repository, formatting, and style. - **Does your code release process account for documentation creation & updates?** - The team regularly updates content as the project is incubating. + Not yet a formal process, but the team regularly updates content. - **Who reviews and approves documentation pull requests?** @@ -351,7 +348,9 @@ We evaluate on the following: - **Does the website have a clear owner/maintainer?** - Yes. + Yes, the GitHub repository has a + [Maintainers](https://github.com/flatcar/Flatcar/blob/main/MAINTAINERS.md) + document. ##### Inclusive language @@ -374,20 +373,26 @@ those only "abort" would necessitate a fix on eight occurrences. ### Recommendations -The Flatcar documentation is naturally evolving into comprehensive and -understandable guidance. Technical savvy readers are well suited to gather the -information they need. New users can still find their path, but they need more -context of the technologies and tools involved, why they're needed, and the -environments they're used in. +The Flatcar documentation is evolving into comprehensive and understandable +guidance. Technical savvy readers are well suited to gather the information they +need. New users can still find their path, but they need more context of the +technologies and tools involved, why they're needed, and the environments +they're used in. #### Information architecture -The high-level recommendations follow a three tier approach to Flatcar -documentation. The first tier (node) should be a Getting Started, followed by -several nodes devoted to operations that span several categories organized by -functionality, and the last tier or group will be related content such as the -Reference and Contributor Documentation. These recommendations are designed to -be malleable. +At a high level, we recommend organizing the Flatcar documentation into three +segments: + +- The first segment is a Getting Started guide. +- The second segment comprises several chapters or guides devoted to operations + that span several categories organized by functionality. +- The last segment contains supporting content such as the Reference and + Contributor Documentation. + +These recommendations are intended to be malleable; as always, the documentation +should serve the needs of the project, and the maintainers and contributors are +the best arbiters of what changes are appropriate to the project. - Create a Getting Started node with the following sections: - Create an "Roadmap" page for users that enables them to determine how they @@ -400,12 +405,11 @@ be malleable. - Prerequisites for the Quickstart. - Any guidance on installing binaries directly or using programs like brew. -- For the middle functional nodes of the table of contents, devise the - categories of tools, technologies, products, and terms pertinent areas for - Flatcar. While these could be under a broader umbrella, such as Operations, - nine or headings in the navigation bar is not too much, and speeds up - discovery. Given a list of about 60 tools, technologies, etc., Copilot devised - the following categories: +- For the middle functional nodes of the TOC, devise the categories of tools, + technologies, products, and terms pertinent areas for Flatcar. While these + could be under a broader umbrella, such as Operations, nine or headings in the + navigation bar is not too much, and speeds up discovery. Given a list of about + 60 tools, technologies, etc., Copilot devised the following categories: - Virtualization and Hypervisors - Cloud and Hosting Platforms - Bare Metal Booting and Installation @@ -415,30 +419,26 @@ be malleable. - Provisioning Configuration and Automation - Container and Orchestration - Work with the team to devise the categories and keep to it! - - Update the top Overview page to accommodate an introduction to the overall documentation to guide users into determining their happy path to accomplish their Flatcar objectives. -- Add at least one architectural diagram to top overviews that depict a - container, a container with Flatcar, and perhaps nodes and clusters. +- Add at least one architectural diagram that depicts a Flatcar container, + clusters, capabilities or other ideas for diagrams. -- Nodes like "Virtual Machines", "Cloud Providers", have subtopics where common - tasks and concepts could be discussed in the overview, leaving the subtopics - with simpler procedures and minimal repetition. +- Sections like "Virtual Machines" and "Cloud Providers" have subtopics where + common tasks and concepts could be discussed in the overview, leaving the + subtopics with simpler procedures and minimal repetition. #### Content maintainability and site mechanics -- Edit each procedural topic, page with code examples, into a semiformal How-to - topic with numbered steps. While the conversational flow is inviting, it - inhibits scanning, predictability, and troubleshooting when needed to - reference a particular code block. No need to go granular, but at least have - then main steps numbered. +- Edit each procedural topic into a formal How-to topic with numbered steps. + While the conversational flow is inviting, it inhibits scanning, + predictability, and troubleshooting when needed to reference a particular code + block. No need to go granular, but at least have then main steps numbered. -- For most, but not every, code block make sure the user has the right context - of where the code is being run. Preceded each step with clauses such as the - following: +- For all code blocks, clearly indicate where the code is to be run. Preceded + each step with clauses such as the following: - On your local machine, use the following command to... - Inside the Flatcar instance, ... - SSH into the instance and then run ... @@ -449,7 +449,9 @@ be malleable. #### Inclusive language and tone - Consider replacing the eight occurrences of "abort". -- Remove occurrences of "easy" where it's implied that a task is easy. +- Remove occurrences of "easy" that could be construed as ableist or + condescending; that is, where they imply that a task should be trivial for the + user. ## Contributor documentation @@ -458,9 +460,9 @@ be developing professional-quality documentation alongside the project code. | Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | 4 | +| Communication methods documented | 3 | | Beginner friendly issue backlog | 4 | -| “New contributor” getting started content | 4 | +| “New contributor” getting started content | 3 | | Project governance documentation | 4 | ### Comments @@ -547,17 +549,20 @@ We evaluate on the following: - **Help wanted issues** - suitable for non-core maintainers. Each documentation page has these two links at the bottom: - - **Edit this page** - link the opens the page for editing in GitHub if a fork + - **Edit this page** - link opens the page for editing in GitHub if a fork exists, otherwise shows the option to fork the repository. - **File documentation issue** - link opens a new GitHub issue. - **Are issues well-documented (i.e., more than just a title)?** Yes, most issues are thoroughly described with detailed proposed solutions. + See the + [Finding Issues](https://github.com/flatcar/Flatcar/blob/main/CONTRIBUTING.md#finding-issues) + section in the Contributing document in the repository. - **Are issues maintained for staleness?** - Generally, yes. + Yes. Confident the team has freshness as a continuing objective. #### New contributor getting started content @@ -593,6 +598,10 @@ We evaluate on the following: - GitHub Discussions: `flatcar/Flatcar/discussions` - Mailing List (Users): `#flatcar-Linux-user` + These and other resources are listed in the + [Onboarding](https://github.com/flatcar/Flatcar/blob/main/ONBOARDING.md) + guide. + #### Project governance documentation One of the CNCF’s core project values is open governance. @@ -601,7 +610,7 @@ We evaluate on the following: - **Is project governance clearly documented?** - Yes, + Yes, the [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) document projects values of openness, fairness, community and participation. For an incubating project, Flatcar is laying the foundation for vigorous @@ -609,9 +618,9 @@ We evaluate on the following: ### Recommendations -The Flatcar team is off to a robust start with it Community outreach and -involvement. All the pertinent criteria has been met for an incubating project. -As the project evolves, the following recommendations should be considered: +The Flatcar team has a robust Community outreach effort and seems to have good +participation. All the criteria have been met for an incubating project. As the +project evolves, the following recommendations should be considered: - Put a link to community participation portal content on the main Flatcar.org website. @@ -790,8 +799,8 @@ We evaluate on the following: #### Other -- Is your website accessible via HTTPS? -- Does HTTP access, if any, redirect to HTTPS? +- Is your website accessible via HTTPS? Yes +- Does HTTP access, if any, redirect to HTTPS? Yes ### Recommendations diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 90ebbc0f..2681bb4f 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -2,7 +2,7 @@ title: Flatcar Issues tags: [Flatcar] created: 2026-04-24 -modified: 2026-04-29 +modified: 2026-04-30 author: Bruce Hamilton (@iRaindrop) --- @@ -284,9 +284,9 @@ Flatcar team to determine key sections and check in the file. The Virtual Machines topic, https://www.flatcar.org/docs/latest/installing/vms/, has a minimal overview with several complex subtopics. Each of the subtopics in -this topic contain a similar workflow that differ only by platform. +this topic contain a similar workflow that differ only by platform. -Here are the common steps determined by Copilot without the details. +Here are the common steps determined by Copilot without the details. 1. Select a Release Channel 1. Download the Appropriate VM Image From 2a8fc091488e97e4c10fda01d843b006649321b0 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Fri, 1 May 2026 00:37:59 -0700 Subject: [PATCH 42/42] Made Dave's sugggestions to issues.doc Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/issues.md | 178 +++++++++++++++----------------- 1 file changed, 86 insertions(+), 92 deletions(-) diff --git a/analyses/2026/flatcar/issues.md b/analyses/2026/flatcar/issues.md index 2681bb4f..6819ba7e 100644 --- a/analyses/2026/flatcar/issues.md +++ b/analyses/2026/flatcar/issues.md @@ -8,32 +8,37 @@ author: Bruce Hamilton (@iRaindrop) +The issues described in this document follow the recommendations for Flatcar in +the [analysis](analysis.md) document. Not all recommendations become issues. + +Teams are encouraged to create GitHub issues based on this document. + ## Sign-off and create the documentation restructure ### Overview -The recommended structure of this analysis happens to also reflect the Flatcar -team's own restructuring proposal. Both naturally arrive at a navigation -structure similar with other container and Kubernetes projects that follow a -natural progression: learn → provision → configure → deploy → other guides, etc. +The recommended structure of this analysis agrees with the Flatcar team's own +restructuring proposal. Both arrive at a navigation structure similar with other +container and Kubernetes projects that follow a natural progression: learn → +provision → configure → deploy → other guides, and so on. -Flatcar differs from a typical application or library documentation set because -it's not so much installation as is its provisioning, or creating, a container -with an immutable operating system. As such the user path, or journey, -throughout the documentation is one of tailoring an efficient first boot of the -container with the desired OS settings and capabilities. +Flatcar's processes differ from those of a typical application because they are +less about installation and more about provisioning a container by installing an +operating system image. As such, the user path throughout the documentation has +the goal of enabling an efficient first boot of the container with a set of +desired OS capabilities. -The recommended structure is a table of contents of just two nodes deep. While -there can be deeper nodes, only two primary levels is recommended and -facilitates a positive user experience by improving discoverability. +The recommended structure is a table of contents (TOC) two nodes deep. While +deeper heading levels exist in the documentation, two levels are recommended for +the TOC to improve discoverability. -The structure should have all top-of-mind concepts and technologies in the first -and second tiers. Some of these nodes need to be broader categories to group -concepts and procedures. Strategic planning should be able to arrive at a -structure where naming changes can be accommodated without re-architecting the -structure. +The structure should have all the most important concepts and technologies in +the first and second tiers. Some of these nodes need to be broader categories to +group concepts and procedures. Contributors should arrive at a consensus on a +structure that features the important information without extensive +re-architecting of the structure. -Here is the recommended structure summary of the top two nodes. +Here is the recommended TOC. | Level A | Level B | | ---------------------------------- | ----------------------------- | @@ -107,32 +112,28 @@ spreadsheet: (link) The detailed sheet has a row for each of the current files in the repository. -The files under node level 2 are not listed in the summary sheet. These -recommended structure does not map the hierarchical sequence of these files on -the website and is assumed there will be churn in this granularity. As the -structure evolves, the deeper structuring should also evolve. +The files under node level 2 are not listed in the summary tab of spreadsheet +(but are on the detailed tab), because the recommended structure does not +prescriptively map the hierarchical positions of these files on the website. We +assume that lower-level files will move around the structure, including up and +down the hierarchy. At this writing, there is initial approval of the recommended structure and after a final approval from the team the structure would be ready to incorporate. A repository restructure is preferred over using a mapping file like Nav.yaml. -The sheet has columns of `old path` and `new path`. The team needs to determine -the names of the directories that correspond to the names of the nodes, e.g. the -"First Boot & Provisioning" could have 'provisioning' as the name of the -directory (folder). - -After approval from the team, a bash script could be coded from the values of -`old path` and `new path` with the `git mv` command to create the new -repository. +The spreadsheet has `old path` and `new path` columns. The team needs to +determine the names of the directories that correspond to the names of the +nodes, e.g. the "First Boot & Provisioning" could have 'provisioning' as the +name of the directory (folder). ## Write a Roadmap topic ### Overview -This topic will be a popular one as it should guide users along a path (or -journey) for knowing what to do to get a Flatcar container going according to -their purpose and needs. +This topic is needed to guide users along a role-determined learning path and +workflow to set up a Flatcar container based on their operational needs. ### Context @@ -142,15 +143,15 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -The roadmap should be a flow-based narrative starting with the list of paths and -each path should have a checklist of prerequisites and high-level steps that -cover provisioning tools and deployment. +The roadmap should be a narrative starting with the list of paths and each path +should have a checklist of prerequisites and high-level steps that cover +provisioning tools and deployment. The user paths include: - Novice user to learn and test - Cloud only user to work with a provider -- On-prem bare metal user +- On-premises bare metal user - Hybrid users Each path should incorporate lists of needed provisioning tools such as VMs with @@ -162,7 +163,7 @@ on configuration and deployment. ### Overview Update or create the overview pages for each of the top two tiers of nodes. The -overview should be brief tour of the node's content. Also update the very top +overview should be a brief tour of the node's content. Also update the very top introduction page. ### Context @@ -173,9 +174,7 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Create or update Overview.md in each top nodes in the Flatcar documentation. If -the node contains several subtopics you can use AI to glean content for an -effective overview. See +Create or update Overview.md in each top node in the Flatcar documentation. See [Consolidate Concepts in Virtual Machines Overview](#consolidate-concepts-in-virtual-machines-overview) issue for an example. @@ -183,8 +182,9 @@ issue for an example. ### Overview -An architectural flow diagram will optimize the documentation. At least one is -needed for the top page and others where applicable and helpful. +An architectural flow diagram will optimize the documentation with a visual +representation of the technology. At least one is needed for the top page and +others where applicable and helpful. ### Context @@ -194,33 +194,22 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -The writer should propose a diagram when the architectural and technical flow is -understood for a subject area or precise process. Use Mermaid Chart to create -the Mermaid code that renders on the web and in Visual Studio Code. - -Prompt AI with a description of the flow to create the code that you can refine -in Mermaid Chart. +The writer should propose a diagram to illustrate the provisioning process flow. ## Add Step Numbering and Context to Procedures ### Overview -Add numbering or bullets to introduce code blocks with context of where the code -is run. - -The Flatcar team already has an issue to add code block capabilities with a copy -button. When this is in place, you can add Markdown fencing syntax with the -language in all pages with code. +Add numbering to introduce code blocks with context of where the code is run. -Currently few if any of the procedural how-to topics have numbered steps. While -in some cases the casual tone is appreciated, it detracts from being able to -reference exact steps and users expect numbering. Use bullets for one or -two-step procedures. +Currently few of the procedural how-to topics have numbered steps. Users expect +numbering. Use a bullet rather than a number for a one-step procedure. New users may be confused as to where a particular code block is run. Is it on -the client machine, in a VM, in a CLI? So introduce code blocks with verbiage -such as "In the VM window in a container, run the following command...". No need -to do it for every block if it's obvious. +the client machine, in a VM, in a CLI? Introduce code blocks with verbiage such +as "In the VM window in a container, run the following command...". This can be +omitted for commands that are clearly a continuation of a command-line session +in the same series of steps. ### Context @@ -230,7 +219,8 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Make these change every time you edit a page with code. +This implementation requires a global approach of working with an inventory of +all topics with code blocks to make these changes. ## Add Content Type and make other updates to metadata @@ -239,8 +229,10 @@ Make these change every time you edit a page with code. The current metadata at the top of Flatcar Markdown files has values for `title`, `link title`, and `weight`. -Adding a `content-type` or `type` value to the metadata will be great for -managing the repository and achieving consistency in the content. +Adding a `content-type` or `type` value to the metadata will help with managing +the repository and achieving consistency in the content. For example, getting +all the files whose `content-type` equals `how-to` would aid in the adding +numbering to procedures task. Apparently the `weight` value is no longer of benefit for the team and there's discussion of removing it. @@ -253,14 +245,19 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -After the restructured repository has stabilized, a Python or other script could -walk the repository and update each Markdown file's metadata. +This requires a global approach to update each Markdown file. Here's a short +list of common content types that apply to most files: + +- tutorial +- how-to +- explanation +- reference ## Add indexing file to repository to assist AI agents -The CTO of CNCF just suggested that all CNCF doc maintainers run a 'sanity -check' with this tool that measures how well AI agents can read, navigate, and -use a documentation site using this tool: https://afdocs.dev/ +The CTO of CNCF just suggested that all CNCF doc maintainers run check with this +tool that measures how well AI agents can read, navigate, and use a +documentation site using this tool: https://afdocs.dev/ One of the main ways to improve AI capabilities is by creating an index file to reside at the root of the repository that contains links to key sections, @@ -305,10 +302,9 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Use AI and your own research to gather key concepts and common procedures that -each of the subtopics have so that the overview contains the conceptual guidance -and common tasks that need not be repeated by the subtopics. Copilot also -offered to write the overview draft from which good ideas could be gleaned. +Document key concepts that are common to each subtopic in the topic overview. +Consider consolidating common procedures into one procedure that works for all +the subtopics. ## Consolidate Concepts in the Cloud Providers Overview @@ -343,10 +339,9 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Use AI and your own research to gather key concepts and common procedures that -each of the subtopics have so that the overview contains the conceptual guidance -and common tasks that need not be repeated by the subtopics. Copilot also -offered to write the overview draft from which good ideas could be gleaned. +Document key concepts that are common to each subtopic in the topic overview. +Consider consolidating common procedures into one procedure that works for all +the subtopics. ## Consolidate Concepts in the Bare Metal Overview @@ -355,12 +350,13 @@ offered to write the overview draft from which good ideas could be gleaned. The Cloud Providers node, https://www.flatcar.org/docs/latest/installing/bare-metal/, has a minimal overview with several complex subtopics. Each of the subtopics in this node -contain a very similar workflow that differ only by platform. To determine the -commonalities among the subtopics, you can use AI. Here is a suggested AI -prompt: "Review the subtopics in this link (link) and provide a list of common -tasks that each of the Bare Metal topics have in common. The aim is to make the -overview page contain most of the concepts so that each of the subtopics can be -simpler How-to topics." +contain a very similar workflow that differ only by platform. + +To determine the commonalities among the subtopics, you can use AI. Here is a +suggested AI prompt: "Review the subtopics in this link (link) and provide a +list of common tasks that each of the Bare Metal topics have in common. The aim +is to make the overview page contain most of the concepts so that each of the +subtopics can be simpler How-to topics." Here are the common steps determined by Copilot without the details. Run the prompt for full context. @@ -381,10 +377,9 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Use AI and your own research to gather key concepts and common procedures that -each of the subtopics have so that the overview contains the conceptual guidance -and common tasks that need not be repeated by the subtopics. Copilot also -offered to write the overview draft from which good ideas could be gleaned. +Document key concepts that are common to each subtopic in the topic overview. +Consider consolidating common procedures into one procedure that works for all +the subtopics. ## Consolidate Concepts in the Community Supported Platforms overview @@ -421,7 +416,6 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `2026/Flatcar`. ### Possible Implementation -Use AI and your own research to gather key concepts and common procedures that -each of the subtopics have so that the overview contains the conceptual guidance -and common tasks that need not be repeated by the subtopics. Copilot also -offered to write the overview draft from which good ideas could be gleaned. +Document key concepts that are common to each subtopic in the topic overview. +Consider consolidating common procedures into one procedure that works for all +the subtopics.