Analysis templates suggested updates

.cspell.yml

@@ -46,6 +46,7 @@ words:
   - Uchechukwu
   - webdev
   - Welsch
+  - llms
   - KubeVirt
   - kubevirt
   - Quickstart

docs/analysis/criteria.md

@@ -2,8 +2,6 @@
 title: Assessment criteria and examples
 ---
 
-# Assessment criteria and examples
-
 We recommend reading the
 [CNCF sandbox project documentation primer](../sandbox-doc-primer.md) before
 reviewing these criteria. The primer contains key definitions concepts that are
@@ -15,24 +13,25 @@ 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:
 
 - 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
   clearly named according to their goals?
 - 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?
@@ -41,6 +40,11 @@ We evaluate on the following:
 - Is content up to date and accurate?
 - Does the documentation separate conceptual, instructional, and reference
   information?
+- If the product builds on or incorporates another product (such as Kubernetes),
+  are there external references where needed to install and configure those
+  products?
+- Does the documentation organization and navigation need a high-level
+  restructuring?
 
 Example:
 
@@ -60,7 +64,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?
@@ -150,10 +155,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:
@@ -172,7 +181,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:
 
@@ -184,7 +193,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:
 
@@ -239,8 +248,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.
@@ -259,22 +268,22 @@ requirements for sandbox projects._
 - Does **project documentation** meet these standards?:
   - Stakeholders / personas are identified and their core needs (in terms of
     docs) documented.
-  - Hosted directly on the website.
+  - Hosted, internally or externally, on the website.
   - The [single-source requirement][] met.
   - Doc is comprehensive, addressing most stakeholder needs.
 
 #### 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
 
 - Is the website repo in an [archived state][]?
 - 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
@@ -295,12 +304,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
@@ -310,8 +315,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.
 
@@ -333,7 +338,7 @@ Example:
 
 - https://helm.sh/
 
-### Case studies/social proof
+### Case studies and social proof
 
 One of the best ways to advertise an open source project is to show other
 organizations using it.
@@ -367,7 +372,7 @@ We evaluate on the following:
   - 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 you site
-    analytics? Provide a sample of the site's current top-10 404s.
+    analytics?
 - 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?
@@ -391,6 +396,23 @@ Example:
 
 - https://kubernetes.io
 
+### AI Optimization and Discoverability
+
+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 leading proposal for an AI-enabling file for websites is at
+  [llms-txt](https://llmstxt.org/).
+
+  Task can be accomplished manually or by tools.
+
 ### Other
 
 - Is your website accessible via HTTPS?

docs/analysis/howto.md

@@ -218,7 +218,7 @@ Create issues in the project documentation GitHub repository for:
 - An umbrella issue that provides a context for the previously created
   individual issues.
 
-[analyses]: ../../analyses/
+[analyses]: ../../analyses
 [criteria]: ./criteria.md
 [project maturity level]: https://www.cncf.io/project-metrics
 [templates]: ./templates/index.md