From 11531afbcf6d200d825e156aa5d2cbaf13969d4c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 8 Jun 2026 22:27:55 -0700 Subject: [PATCH 01/13] minor edit to add doc for commenting Signed-off-by: Bruce Hamilton --- docs/analysis/templates/analysis.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index 2551255..2da4753 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -23,6 +23,9 @@ TO USE THIS TEMPLATE, search and replace the named IDs: - `_PROJECT-DOC-REPO_`: repository where the project technical documentation is stored; this might be its own repo or a directory in the project main repo +Replace link placeholders in brackets, such as [_PROJECT_][project-website], +with the actual link surrounded by parenthesis. + For the analysis procedure, see [Analysis how-to](../howto.md). > Note: delete this "About this template" section after you have customized this From 30e402c237653529eecc8ff7ba104f7b923c9373 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 13:30:56 -0700 Subject: [PATCH 02/13] added AI section Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 9045bb0..ea2bc6b 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -126,6 +126,27 @@ We evaluate on the following: [Inclusive Naming Initiative](https://inclusivenaming.org) website? - Does the project use language like "simple", "easy", etc.? +### AI Optimizaiton and Discoverability + +Configurations for AI agents to optimizie the understanding of content are +emerging and should be utilized. + +We evaluate on the following: + +- Is there an llms.txt file in the root of the website or documentation + repository? + + llms.txt is a proposed open standard for a Markdown file that websites can + host at the root (e.g., https://example.com/llms.txt). It helps large language + models (LLMs) and AI agents quickly understand a site's purpose, key content, + and where to find reliable information—similar to how robots.txt guides + crawlers or sitemap.xml lists pages, but optimized for AI inference (usage at + query time) rather than broad indexing. + + See https://llmstxt.org/ + + Task can be accomplished manually or by various tools and plugins. + ## Contributor documentation ### Communication methods documented From 2edb12ae2022409e5297d55e3fa69d3f84daaf0d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 13:35:10 -0700 Subject: [PATCH 03/13] spelling fix Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index ea2bc6b..eb6dc85 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -126,7 +126,7 @@ We evaluate on the following: [Inclusive Naming Initiative](https://inclusivenaming.org) website? - Does the project use language like "simple", "easy", etc.? -### AI Optimizaiton and Discoverability +### AI Optimization and Discoverability Configurations for AI agents to optimizie the understanding of content are emerging and should be utilized. From bc2b86dc950ab3e6af1bb52bcd5442cf301907e8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 13:40:52 -0700 Subject: [PATCH 04/13] removed unneeded example link Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index eb6dc85..502f4b3 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -137,11 +137,11 @@ We evaluate on the following: repository? llms.txt is a proposed open standard for a Markdown file that websites can - host at the root (e.g., https://example.com/llms.txt). It helps large language - models (LLMs) and AI agents quickly understand a site's purpose, key content, - and where to find reliable information—similar to how robots.txt guides - crawlers or sitemap.xml lists pages, but optimized for AI inference (usage at - query time) rather than broad indexing. + host at the root. It helps large language models (LLMs) and AI agents quickly + understand a site's purpose, key content, and where to find reliable + information—similar to how robots.txt guides crawlers or sitemap.xml lists + pages, but optimized for AI inference (usage at query time) rather than broad + indexing. See https://llmstxt.org/ From be4fbffe8f0c84d6e96ece7ece0085a1141b79ea Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 13:47:42 -0700 Subject: [PATCH 05/13] spelling - fomratting fixes Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 502f4b3..d4674aa 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -128,7 +128,7 @@ We evaluate on the following: ### AI Optimization and Discoverability -Configurations for AI agents to optimizie the understanding of content are +Configurations for AI agents to optimize the understanding of content are emerging and should be utilized. We evaluate on the following: @@ -139,9 +139,7 @@ We evaluate on the following: llms.txt is a proposed open standard for a Markdown file that websites can host at the root. It helps large language models (LLMs) and AI agents quickly understand a site's purpose, key content, and where to find reliable - information—similar to how robots.txt guides crawlers or sitemap.xml lists - pages, but optimized for AI inference (usage at query time) rather than broad - indexing. + information. See https://llmstxt.org/ From c754d478f3beb406a3964dccd4a4d43b1685b644 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 13:53:37 -0700 Subject: [PATCH 06/13] put llms in code to fix spelling Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index d4674aa..d5de769 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -133,10 +133,10 @@ emerging and should be utilized. We evaluate on the following: -- Is there an llms.txt file in the root of the website or documentation +- Is there an `llms.txt` file in the root of the website or documentation repository? - llms.txt is a proposed open standard for a Markdown file that websites can + `llms.txt` is a proposed open standard for a Markdown file that websites can host at the root. It helps large language models (LLMs) and AI agents quickly understand a site's purpose, key content, and where to find reliable information. From dc567e2dd653f198919dfc75cafd08b4a7ddfbb8 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 14:02:39 -0700 Subject: [PATCH 07/13] trying quotes Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index d5de769..00a6def 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -133,17 +133,17 @@ emerging and should be utilized. We evaluate on the following: -- Is there an `llms.txt` file in the root of the website or documentation +- Is there an "llms.txt" file in the root of the website or documentation repository? - `llms.txt` is a proposed open standard for a Markdown file that websites can - host at the root. It helps large language models (LLMs) and AI agents quickly - understand a site's purpose, key content, and where to find reliable - information. + The "llms.txt" file is a proposed open standard for a Markdown file that + websites can host at the root. It helps large language models (LLMs) and AI + agents quickly understand a site's purpose, key content, and where to find + reliable information. - See https://llmstxt.org/ + For more informatino see https://llmstxt.org/ - Task can be accomplished manually or by various tools and plugins. + Task can be accomplished manually or by tools. ## Contributor documentation From ae6acf801a6bce2e844e895554973b4afb33163d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 14:12:34 -0700 Subject: [PATCH 08/13] changed llms.txt to _AGENT_ placedholder Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 00a6def..af4ba11 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -133,13 +133,13 @@ emerging and should be utilized. We evaluate on the following: -- Is there an "llms.txt" file in the root of the website or documentation +- Is there an _AGENT_ file in the root of the website or documentation repository? - The "llms.txt" file is a proposed open standard for a Markdown file that - websites can host at the root. It helps large language models (LLMs) and AI - agents quickly understand a site's purpose, key content, and where to find - reliable information. + The _AGENT_ file is a proposed open standard for a Markdown file that websites + can host at the root. It helps large language models (LLMs) and AI agents + quickly understand a site's purpose, key content, and where to find reliable + information. For more informatino see https://llmstxt.org/ From 32219eb379a0844e1e0d7eb9becba0e0d885b63c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 14:18:03 -0700 Subject: [PATCH 09/13] spelling fix Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index af4ba11..ad72704 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -141,7 +141,7 @@ We evaluate on the following: quickly understand a site's purpose, key content, and where to find reliable information. - For more informatino see https://llmstxt.org/ + For more information, see https://llmstxt.org/ Task can be accomplished manually or by tools. From 3253ec1123d0f8c01c523dc472abbf0f085cf0bb Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 17:02:39 -0700 Subject: [PATCH 10/13] added back llms.txt Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index ad72704..58214c6 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -133,10 +133,10 @@ emerging and should be utilized. We evaluate on the following: -- Is there an _AGENT_ file in the root of the website or documentation +- Is there an llms.txt file in the root of the website or documentation repository? - The _AGENT_ file is a proposed open standard for a Markdown file that websites + The llms.txt file is a proposed open standard for a Markdown file that websites can host at the root. It helps large language models (LLMs) and AI agents quickly understand a site's purpose, key content, and where to find reliable information. From 0d1e328ac29594bbc3b3358b4a7d294b45f31070 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 17:20:33 -0700 Subject: [PATCH 11/13] ran prittier Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 58214c6..977e2dd 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -136,10 +136,10 @@ We evaluate on the following: - Is there an llms.txt file in the root of the website or documentation repository? - The llms.txt file is a proposed open standard for a Markdown file that websites - can host at the root. It helps large language models (LLMs) and AI agents - quickly understand a site's purpose, key content, and where to find reliable - information. + The llms.txt file is a proposed open standard for a Markdown file that + websites can host at the root. It helps large language models (LLMs) and AI + agents quickly understand a site's purpose, key content, and where to find + reliable information. For more information, see https://llmstxt.org/ From 3dcf00a3bcc406c392b2e77389b1ab4bf8c1bfad Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 10 Jun 2026 18:21:45 -0700 Subject: [PATCH 12/13] added llms to word list Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.cspell.yml b/.cspell.yml index bf753db..a58d2f9 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -45,3 +45,4 @@ words: - Uchechukwu - webdev - Welsch + - llms From b45666e8887afda16c539faab743cef62ff6a352 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Tue, 16 Jun 2026 21:37:27 -0700 Subject: [PATCH 13/13] Applied Dave's suggestions Signed-off-by: Bruce Hamilton --- docs/analysis/criteria.md | 54 ++++++++++++++--------------- docs/analysis/templates/analysis.md | 21 +++++++---- 2 files changed, 42 insertions(+), 33 deletions(-) diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 977e2dd..b71d961 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -15,7 +15,7 @@ referred to in the criteria. How your technical information is organized, laid out, and presented. This includes structure (pages/subpages/sections/subsections), information types -(conceptual/instructional/reference), and matching documentation content to user +(conceptual/instructional/reference), and content that matches user expectations. We evaluate on the following: @@ -23,7 +23,8 @@ We evaluate on the following: - Is there high level conceptual content? - Is every product feature documented? - Does the documentation define all user roles (personas) for the product? -- Are there instructions (tasks, tutorials) documented for features? +- Do instructions (tasks, tutorials) cover the intended purposes of all + user-facing features? - Are there instructions for all major use cases for each user role? - Are tasks organized by user role and use case? - Does instructional content demonstrate atomicity — are individual tasks @@ -31,8 +32,8 @@ We evaluate on the following: - Are tasks written as numbered step-by-step instructions? - Do task descriptions in headings and the TOC describe the task with a verb phrase? -- Is the documentation free of any key features which are documented but missing - task documentation? +- Are there any features that are documented (for example, described + conceptually) but are missing task documentation? - Is the “happy path” — the most common use case — documented? - If the documentation does not suffice, is there a clear escalation path for users needing more help? @@ -60,7 +61,8 @@ We evaluate on the following: - Are different types of installation documented (development, test, production) if necessary? - If needed, are multiple OSes documented? -- Do users know where to go after reading the getting started guide? +- Is there guidance for what to read next after reading the getting started + guide? - Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? - Is there easily copy-pastable sample code or other example content? @@ -128,20 +130,18 @@ We evaluate on the following: ### AI Optimization and Discoverability -Configurations for AI agents to optimize the understanding of content are -emerging and should be utilized. +Tools and techniques are emerging that enable AI agents to use documentation as +input. For example, many repositories now include "AI-friendly" Markdown files +that enable LLMs to ingest content. We encourage projects to optimize for +AI-based documentation use. We evaluate on the following: - Is there an llms.txt file in the root of the website or documentation repository? - The llms.txt file is a proposed open standard for a Markdown file that - websites can host at the root. It helps large language models (LLMs) and AI - agents quickly understand a site's purpose, key content, and where to find - reliable information. - - For more information, see https://llmstxt.org/ + The leading proposal for an AI-enabling file for websites is at + [llms-txt](https://llmstxt.org/ llms.txt). Task can be accomplished manually or by tools. @@ -169,10 +169,14 @@ Example: We evaluate on the following: -- Are docs issues well-triaged? +- Are docs issues triaged with respect to effort level and required expertise? - 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 documented with: + - What is missing, incorrect, or improperly presented? + - What impact the issue has on documentation users? + - A suggested remedy? + - An estimate of the effort required to address the issue? - Are issues maintained for staleness? Example: @@ -191,7 +195,7 @@ We evaluate on the following: - Do you have a community repository or section on your website? - Is there a document specifically welcoming new contributors and documenting a first contribution process? -- Can new users find where to get help? +- Are there prominently displayed resources for new users to find help? Example: @@ -203,7 +207,7 @@ One of the CNCF’s core project values is open governance. We evaluate on the following: -- Is project governance clearly documented? +- Does the project governance align with CNCF guidelines and values? Example: @@ -258,8 +262,8 @@ requirements for sandbox projects._ Incubating status. - Is there rudimentary **project documentation**, or a placeholder or substitute? - - It is acceptable at this maturity level to link out to documentation that - hasn't yet been integrated into the website. + - It is acceptable at this maturity level to link to documentation that hasn't + yet been integrated into the website. - _Example_: website with a single homepage, without any documentation or, as was mentioned above, linking out to an external (preexisting) source for docs. @@ -285,7 +289,7 @@ requirements for sandbox projects._ #### Graduated - Are follow-through actions from the [Docs assessment][] complete? -- Does **project documentation** fully addresses the needs of key stakeholders? +- Does **project documentation** fully addresses the needs of stakeholders? #### Archived @@ -293,7 +297,7 @@ requirements for sandbox projects._ - Is the archived status of the project obvious to those visiting the website, such as through the use of a prominent banner? - If a successor project exists, are there links to its website and/or migration - documentation. + documentation? [archived state]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories @@ -314,12 +318,8 @@ We evaluate on the following: - Is the website usable from mobile? - Are doc pages readable? -- Are all or 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? -- 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? [mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first @@ -329,8 +329,8 @@ Plan for suitable [accessibility][] measures for your website. We evaluate on the following: - 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? +- Are all vital website features usable using a keyboard only? +- Does text-to-speech offer listeners a usable experience? It is up to each project to set their own guidelines. diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index 2da4753..8acb9fa 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -24,7 +24,7 @@ TO USE THIS TEMPLATE, search and replace the named IDs: stored; this might be its own repo or a directory in the project main repo Replace link placeholders in brackets, such as [_PROJECT_][project-website], -with the actual link surrounded by parenthesis. +with a Markdown-style link. For the analysis procedure, see [Analysis how-to](../howto.md). @@ -89,11 +89,14 @@ This document is divided into three sections that represent three major areas of concern: - **Project documentation:** concerns documentation for users of the _PROJECT_ - software, aimed at people who intend to use the project software + software, aimed at people who intend to use the project software. - **Contributor documentation:** concerns documentation for new and existing - contributors to the _PROJECT_ OSS project + contributors to the _PROJECT_ OSS project. - **Website:** concerns the mechanics of publishing the documentation, and - includes branding, website structure, and maintainability + includes branding, website structure, and maintainability. + +A fourth area of concern, AI optimization and discovery, might be included in +this analysis. If so, it is discussed in a separate document, `ai-guidance.md`. Each section begins with summary ratings based on a rubric with appropriate [criteria] for the section, then proceeds to: @@ -103,6 +106,12 @@ Each section begins with summary ratings based on a rubric with appropriate - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. +> Author's note: We recommend writing implementation notes only for large +> projects. An implementation plan can bridge the gap between the high-level +> recommendations in this document and individual issues entered in the doc +> repo. Remove the sentences about the implementation doc if you didn't write +> one. + The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in @@ -178,8 +187,8 @@ documentation. We evaluate on the following: complete? (i.e., each product feature is documented) - Are there step-by-step instructions (tasks, tutorials) documented for features? -- Are there any key features which are documented but missing task - documentation? +- Are there any features that are documented (for example, described + conceptually) but are missing task documentation? - Is the “happy path”/most common use case documented? Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?)