Skip to content

docs: restructure README around reader personas#64

Merged
eskenazit merged 2 commits into
mainfrom
docs/readme-personas
Jun 26, 2026
Merged

docs: restructure README around reader personas#64
eskenazit merged 2 commits into
mainfrom
docs/readme-personas

Conversation

@jlouvel

@jlouvel jlouvel commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

Related Issue

Closes #63


What does this PR do?

Restructures the Polychro README.md around reader personas, mirroring the Ikanos README change (naftiko/ikanos#620) and based on the same user feedback: the README opened with dense, cross-domain jargon before the reader could tell whether the project was for them.

Changes:

  • Adds a "Polychro in one sentence" jargon-light hook at the top.
  • Adds a "Who are you?" section with three persona blocks in a "Who you are → What Polychro can do for you" shape:
    • 🤖 You're building AI agents or tools (MCP, in-process, agent-format output)
    • 🛡️ You run CI or a platform (GitHub Action, SARIF, one binary, governance rulesets)
    • 📐 You author specs or rules (Spectral rulesets, polyglot custom functions, validator SPI)
  • Each persona links to the relevant guide to start with (MCP server / GitHub Action / Rulesets).
  • Renames "What Polychro is" to "Under the hood" and keeps the technical tables, quick start, and comparison below as reference.

No feature claims are added or changed — this is purely a structure/onboarding improvement.

The companion docs changes (landing page + new who-is-it-for.md) are in the Shipyard repo.


Tests

No tests — documentation-only change. Verified Markdown renders cleanly and the referenced guide links resolve.


Checklist

  • CI is green (build, tests, schema validation, security scans)
  • Rebased on latest main
  • Small and focused — one concern per PR
  • Commit messages follow Conventional Commits

Agent Context (optional)

agent_name: GitHub Copilot
tool: vscode
confidence: high
discovery_method: user_report

jlouvel added 2 commits June 26, 2026 13:36
- Replace the long persona deep-dives with a concise "What that means for you" section
- De-bold the intro and lead with the open source AI linter framing
- Trim the feature table and point to Features for the full list
- Condense the "What it is not" section
- Convert absolute shipyard.naftiko.io links to relative docs paths
- Add a "Continue reading" section linking the core docs pages
@jlouvel jlouvel requested a review from eskenazit June 26, 2026 13:55

@eskenazit eskenazit left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM

@eskenazit eskenazit merged commit bf2b4c0 into main Jun 26, 2026
2 checks passed
@eskenazit eskenazit deleted the docs/readme-personas branch June 26, 2026 14:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: restructure README and docs landing around reader personas

2 participants