Flatcar docs analysis - writing and updates

analyses/2026/flatcar/analysis.md

@@ -6,8 +6,7 @@ modified: 2026-04-04
 author: Bruce Hamilton (@iRaindrop)
 ---
 
-<!-- markdownlint-disable line-length -->
-<!-- markdownlint-disable no-duplicate-heading link-image-reference-definitions -->
+<!-- markdownlint-disable no-duplicate-heading -->
 
 ## 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
@@ -273,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?**
@@ -305,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
 
@@ -317,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
 
@@ -338,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
 
@@ -369,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
 
@@ -461,47 +461,103 @@ 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          | 4              |
+| Beginner friendly issue backlog           | 4              |
+| “New contributor” getting started content | 4              |
+| Project governance documentation          | 4              |
 
 ### Comments
 
-> AUTHOR NOTE: make any overall comments about the Contributor Documentation
-> here.
-
 The following sections contain brief assessments of each element of the
 Contributor Documentation rubric.
 
-> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet
-> these criteria. Keep in mind that much of the contributor documentation might
-> be contained in the documentation repository. (Criteria are copied from
-> criteria.md)
-
 #### Communication methods documented
 
 One of the easiest ways to attract new contributors is making sure they know how
 to reach you.
 
+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 team provides links to aggregated GitHub issues for newcomers and advanced
+users to work on.
+
 We evaluate on the following:
 
-- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked
-  from your website?
-- Is there a direct link to your GitHub organization/repository?
-- Are weekly/monthly project meetings documented? Is it clear how someone can
-  join those meetings?
-- Are mailing lists documented?
+- **Is there a Slack 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. 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
+
+  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?**
+
+  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
 
 #### 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)?**
+
+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.
+
+- **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
 
@@ -511,17 +567,43 @@ 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](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.
+
+- **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`
 
 #### Project governance documentation
 
 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
 
@@ -725,12 +807,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
@@ -743,10 +819,11 @@ 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]: ../../../docs/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 -->