From 0a66134c6459795cacdde8d157619ff6caa8f433 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 11 May 2026 13:14:42 -0700 Subject: [PATCH 1/2] removed website analysis section Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 222 +----------------------------- 1 file changed, 4 insertions(+), 218 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 2bda88a..18f5fc3 100644 --- a/analyses/2026/flatcar/analysis.md +++ b/analyses/2026/flatcar/analysis.md @@ -12,7 +12,7 @@ author: Bruce Hamilton (@iRaindrop) This document is an analysis of the effectiveness and completeness of the [Flatcar](https://www.flatcar.org/docs/latest) open source software (OSS) -project's documentation and website. It is funded by the CNCF Foundation as part +project's documentation. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. @@ -33,14 +33,13 @@ up by contributors to improve the documentation. This document: -- Analyzes the current Flatcar technical documentation and website +- Analyzes the current Flatcar technical documentation - Compares existing documentation against the CNCF’s standards - Recommends a program of key improvements with the largest return on investment ### Scope of analysis -The documentation discussed here includes the entire contents of the website, -the technical documentation, and documentation for contributors and users on the +The documentation discussed here includes the entire contents of the technical documentation and documentation for contributors and users on the Flatcar GitHub repository. The Flatcar website and documentation are written in Markdown and are compiled @@ -69,8 +68,6 @@ concern: software, aimed at people who intend to use the project software - **Contributor documentation:** concerns documentation for new and existing contributors to the Flatcar OSS project -- **Website:** concerns the mechanics of publishing the documentation, and - includes branding, website structure, and maintainability Each section begins with summary ratings based on a rubric with appropriate criteria for the section, then proceeds to: @@ -97,10 +94,9 @@ to their area of concern: - [Project documentation](#project-documentation) - [Contributor documentation](#contributor-documentation) -- [Website and documentation infrastructure](#website-and-infrastructure) Examples of CNCF documentation that demonstrate the analysis criteria are linked -from the [criteria] specification. +from the [criteria](../../../docs/analysis/criteria.md) specification. #### Recommendations, requirements, and best practices @@ -669,213 +665,3 @@ appropriate. The [Flatcar Project Governance](https://github.com/flatcar/Flatcar/blob/main/governance.md) document is comprehensive, and appears well-maintained and up-to-date. - -## Website and infrastructure - -> The analysis for this section is not complete. - -Flatcar is an **incubating** project of CNCF. This means that the project should -be developing professional-quality documentation alongside the project code. - -| Criterion | [Rating (1-5)] | -| ------------------------------------------- | -------------- | -| Single-source for all files | [rating (1-5)] | -| Meets min website req. (for maturity level) | [rating (1-5)] | -| Usability, accessibility, and design | [rating (1-5)] | -| Branding and design | [rating (1-5)] | -| Case studies/social proof | [rating (1-5)] | -| SEO, Analytics, and site-local search | [rating (1-5)] | -| Maintenance planning | [rating (1-5)] | -| A11y plan & implementation | [rating (1-5)] | -| Mobile-first plan & implementation | [rating (1-5)] | -| HTTPS access & HTTP redirect | [rating (1-5)] | -| Google Analytics 4 for production only | [rating (1-5)] | -| Indexing allowed for production server only | [rating (1-5)] | -| Within site / local search | [rating (1-5)] | -| Account custodians are documented | [rating (1-5)] | - -### Comments - -> AUTHOR NOTE: make any overall comments about the Website and documentation -> infrastructure here. - -The following sections contain brief assessments of each element of the Website -and documentation infrastructure rubric. - -> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet -> these criteria. Keep in mind that much of the website infrastructure criteria -> depend on the tools (static site generator, website framework and hosting, -> analytics tools, etc.) and processes (project CI, release procedures, -> governance, etc.) used to produce the documentation. (Criteria are copied from -> criteria.md) - -#### Single-source requirement - -Source files for _all website pages_ should reside in a single repo. Among other -problems, keeping source files in two places: - -- confuses contributors -- requires you to keep two sources in sync -- increases the likelihood of errors -- makes it more complicated to generate the documentation from source files - -Ideally, all website files should be in the **website repo** itself. -Alternatively, files should be brought into the website repo via [git -submodules][git-submodules]. - -If a project chooses to keep source files in multiple repos, they need a clearly -documented strategy for managing mirrored files and new contributions. - -#### Minimal website requirements - -Listed here are the minimal website requirements for projects based on their -[maturity level][maturity-level], either incubating or graduated. (These are the -only two levels for which a tech docs analysis can be requested.) - - - -| Criterion | Incubating Requirement | Graduated Requirement | -| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | -| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | -| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | -| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | -| **Project doc**: hosting | Hosted directly | All Hosted directly | -| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | - - - -[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[maturity-level]: - https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations -[cncf-servicedesk]: https://servicedesk.cncf.io - -#### Usability, accessibility and devices - -Most CNCF websites are accessed from mobile and other non-desktop devices at -least 10-20% of the time. Planning for this early in your website's design will -be much less effort than retrofitting a desktop-first design. - -- Is the website usable from mobile? -- Are doc pages readable? -- Are all / most website features accessible from mobile -- such as the top-nav, - site search and in-page table of contents? -- Might a [mobile-first] design make sense for your project? - -[mobile-first]: - https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first - -Plan for suitable [accessibility][] measures for your website. For example: - -- Are color contrasts significant enough for color-impaired readers? -- Are most website features usable using a keyboard only? -- Does text-to-speech offer listeners a good experience? - -It is up to each project to set their own guidelines. - -[accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility - -#### Branding and design - -CNCF seeks to support enterprise-ready open source software. A key aspect of -this is branding and marketing. - -We evaluate on the following: - -- Is there an easily recognizable brand for the project (logo + color scheme) - clearly identifiable? -- Is the brand used across the website consistently? -- The website’s typography clean and well-suited for reading? - -#### Case studies/social proof - -One of the best ways to advertise an open source project is to show other -organizations using it. - -We evaluate on the following: - -- Are there case studies available for the project and are they documented on - the website? -- Are there user testimonials available? -- Is there an active project blog? -- Are there community talks for the project and are they present on the website? -- Is there a logo wall of users/participating organizations? - -#### SEO, Analytics and site-local search - -SEO helps users find your project, and it's documentation, and analytics helps -you monitor site traffic and diagnose issues like page 404s. Intra-site search, -while optional, can offer your readers a site-focused search results. - -We evaluate on the following: - -- Analytics: - - Is analytics enabled for the production server? - - Is analytics disabled for all other deploys? - - If your project used Google Analytics, have you migrated to GA4? - - Can Page-not-found (404) reports easily be generated from your site - analytics? Provide a sample of the site's current top-10 404s. -- Is site indexing supported for the production server, while disabled for - website previews and builds for non-default branches? -- Is local intra-site search available from the website? -- Are the current custodian(s) of the following accounts clearly documented: - analytics, Google Search Console, site-search (such as Google CSE or Algolia) - -#### Maintenance planning - -Website maintenance is an important part of project success, especially when -project maintainers aren’t web developers. - -We evaluate on the following: - -- Is your website tooling well-supported by the community (i.e., Hugo with the - Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) -- Are you actively cultivating website maintainers from within the community? -- Are site build times reasonable? -- Do site maintainers have adequate permissions? - -#### Other - -- Is your website accessible via HTTPS? Yes -- Does HTTP access, if any, redirect to HTTPS? Yes - -### Recommendations - -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - -#### Single-source requirement - -#### Minimal website requirements - -#### Usability, accessibility and devices - -#### Branding and design - -#### Case studies/social proof - -#### SEO, Analytics and site-local search - -#### Maintenance planning - -#### Other - -#### References and notes - -##### Rating values - -The numeric rating values used in this document are as follows - -1. Not present -2. Needs improvement -3. Meets standards -4. Meets or exceeds standards -5. Exemplary - - From 8ea52faa229c07b01b0e344ce527958d672256de Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 11 May 2026 13:31:37 -0700 Subject: [PATCH 2/2] ran prittier Signed-off-by: Bruce Hamilton --- analyses/2026/flatcar/analysis.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/analyses/2026/flatcar/analysis.md b/analyses/2026/flatcar/analysis.md index 18f5fc3..4654f2c 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-05-05 +modified: 2026-05-11 author: Bruce Hamilton (@iRaindrop) --- @@ -12,9 +12,9 @@ author: Bruce Hamilton (@iRaindrop) This document is an analysis of the effectiveness and completeness of the [Flatcar](https://www.flatcar.org/docs/latest) open source software (OSS) -project's documentation. It is funded by the CNCF Foundation as part -of its overall effort to incubate, grow, and graduate open source cloud native -software projects. +project's documentation. It is funded by the CNCF Foundation as part of its +overall effort to incubate, grow, and graduate open source cloud native software +projects. According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first @@ -39,8 +39,9 @@ This document: ### Scope of analysis -The documentation discussed here includes the entire contents of the technical documentation and documentation for contributors and users on the -Flatcar GitHub repository. +The documentation discussed here includes the entire contents of the technical +documentation and documentation for contributors and users on the Flatcar GitHub +repository. The Flatcar website and documentation are written in Markdown and are compiled using the Hugo generator with the Flatcar theme and served from a GitHub