From a39f7d76ceade49e62ffbb4e3f66ef7c2047192d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sat, 11 Apr 2026 22:20:12 -0700 Subject: [PATCH 1/5] 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 2/5] 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 3/5] 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 4/5] 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 5/5] 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