Skip to content

Analysis templates suggested updates #357

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
iRaindrop wants to merge 13 commits into
base: main
Choose a base branch
from
+23 −0
Draft

Analysis templates suggested updates #357

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
11531af
minor edit to add doc for commenting
iRaindrop Jun 9, 2026
0180b2b
Merge branch 'main' into analysis-templates-updates
iRaindrop Jun 9, 2026
30e402c
added AI section
iRaindrop Jun 10, 2026
2edb12a
spelling fix
iRaindrop Jun 10, 2026
bc2b86d
removed unneeded example link
iRaindrop Jun 10, 2026
be4fbff
spelling - fomratting fixes
iRaindrop Jun 10, 2026
c754d47
put llms in code to fix spelling
iRaindrop Jun 10, 2026
dc567e2
trying quotes
iRaindrop Jun 10, 2026
ae6acf8
changed llms.txt to _AGENT_ placedholder
iRaindrop Jun 10, 2026
32219eb
spelling fix
iRaindrop Jun 10, 2026
3253ec1
added back llms.txt
iRaindrop Jun 11, 2026
0d1e328
ran prittier
iRaindrop Jun 11, 2026
3dcf00a
added llms to word list
iRaindrop Jun 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .cspell.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,4 @@ words:
- Uchechukwu
- webdev
- Welsch
- llms
19 changes: 19 additions & 0 deletions docs/analysis/criteria.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,25 @@ We evaluate on the following:
[Inclusive Naming Initiative](https://inclusivenaming.org) website?
- Does the project use language like "simple", "easy", etc.?

### AI Optimization and Discoverability

@iRaindrop iRaindrop Jun 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New section. Please opine.

UPDATE: Nate and I discussed this and agreed it would be better in a separate topic. @nate-double-u - how about naming it ai-guidance.md?

@dwelsch-esi dwelsch-esi Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The currently popular description seems to be "AI friendly." I like "optimization and discovery" better -- it's more precise -- but I'd put "AI friendly" in the description somewhere for searchability.

What's the rationale for having a separate document?


Configurations for AI agents to optimize the understanding of content are
emerging and should be utilized.
Comment on lines +131 to +132

@dwelsch-esi dwelsch-esi Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

I strongly object to language that anthropomorphizes AI, for example the idea that it "understands" documentation. I'll die on this hill.


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.
Comment on lines +139 to +142

@dwelsch-esi dwelsch-esi Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 leading proposal for an AI-enabling file for websites is at [llms-txt](https://llmstxt.org/ llms.txt).


For more information, see https://llmstxt.org/

@dwelsch-esi dwelsch-esi Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For more information, see https://llmstxt.org/


Task can be accomplished manually or by tools.

@dwelsch-esi dwelsch-esi Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What task? What tools? Is this a continuation of the AI tools criteria? If so, it should be a bullet item and explain why it's a criterion.


## Contributor documentation

### Communication methods documented
Expand Down
3 changes: 3 additions & 0 deletions docs/analysis/templates/analysis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@dwelsch-esi dwelsch-esi Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
with the actual link surrounded by parenthesis.
with a Markdown-style link.


@iRaindrop iRaindrop Jun 11, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added this. Remove if you think its not needed.

For the analysis procedure, see [Analysis how-to](../howto.md).

> Note: delete this "About this template" section after you have customized this
Expand Down