Conversation
Contributor
|
Really like this! |
Contributor
|
Also should add an image? Often explains more than a 1000 words cc @pronskiy |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
1. Purpose
I propose that the README should serve 3 main goals:
The README provides the explanation for evaluation, a clear path to trying it, and navigation for returning readers; the opening need not explain the whole product or setup instructions.
Below are a few proposed example reader scenarios:
Detailed usage belongs in
docs/user/; build instructions and architecture belong in the contributor and developer guides. Linking to these avoids duplicating instructions that can drift.2. Changes
docs/user/quickstart.md.CONTRIBUTING.mdanddocs/dev/architecture.mdalready cover them.llms.txtin the top navigation and bothllms.txtandllms-full.txtunder Docs.3. Open questions
4. Contribution status
Draft shared for discussion under GOVERNANCE.md’s “Draft vs ready” policy; no backing issue is required for this stage. The opening pitch and performance claims remain unsettled. Before requesting formal review, confirm whether this qualifies for the documentation fast-lane or needs an accepted issue.
Blast radius:
README.mdonly; no runtime, API, schema, or storage behavior changes.5. Checklist
6. Local verification
git diff --check -- README.md— passed.bash scripts/check-agents-md.sh— passed.python3 scripts/check-docs.py— passed (153 Markdown files).typos— not run; executable unavailable locally.