Skip to content

docs(profile): dedupe and tighten the bottom half of README#44

Merged
amavashev merged 1 commit into
mainfrom
docs/profile-readme-cleanup
May 2, 2026
Merged

docs(profile): dedupe and tighten the bottom half of README#44
amavashev merged 1 commit into
mainfrom
docs/profile-readme-cleanup

Conversation

@amavashev
Copy link
Copy Markdown
Contributor

Cuts the org profile README from 354 → 206 lines (-42%) by collapsing overlapping sections. No content removed in spirit; ~5 sections that all answered the same question are merged into one each.

Why this PR

The bottom half had grown into ~14 sections with substantial overlap. Specifically:

  • 5 sections all answered "what IS Runcycles?" ("What is Cycles?" + "What is Runcycles?" + "How it works" + "Quick mental model" + "The ecosystem")
  • 4 sections all answered "who is this for?" ("Typical use cases" + "Who Runcycles is for" + "Where Runcycles fits" + "When to use Runcycles")

A first-time visitor doesn't read 354 lines on a profile README — they skim. Cutting the redundancy makes the surviving prose actually land.

What changed

Before After
"What is Cycles?" + "What is Runcycles?" + "Quick mental model" + "The ecosystem" (4 sections) Single "What this is" (1 section, 3 paragraphs)
"Typical use cases" + "Who Runcycles is for" + "Where Runcycles fits" + "When to use Runcycles" (4 sections) Single "Who it's for" (1 section, 3 paragraphs)
"How it works" (15 lines explaining the loop) 4 lines pointing at the diagram + Try-it snippets above
"What Runcycles enforces" with 5 sub-headings 5-bullet list
"Status" (vague) "Status" + CHANGELOG link (load-bearing)

What was dropped

  • Mid-page "👉 Learn more" CTA at the old line 131 — sat before 220 more lines of content, read as a false page-end
  • Web3 / EVM / "blockchain transactions" mentions + the defensive "Web3 is one surface area, not a requirement" one-liner. Not active product positioning; reads as holdover
  • Broken docs URL (`runcycles.github.io/docs` → fixed to the canonical `runcycles.io`)

What was kept verbatim

  • Top half (badges, hook, value-prop bullets, CTA links, architecture diagram, GIF demo, Try-it MCP+Python snippets, Start-here repo list) — untouched
  • "Why Runcycles exists" — distinct motivation, kept (slightly compressed from 11 short lines to 2 paragraphs)
  • "What Runcycles is not" — orthogonal differentiator, kept verbatim
  • "Design principles" — short and load-bearing, kept verbatim

Test plan

  • On the PR's Files-changed → View file, confirm rendered output reads cleanly top-to-bottom
  • Verify no broken links (the `runcycles.io` and ARCHITECTURE.md links resolve)
  • Mobile: confirm no horizontal-scroll issues
  • After merge, sanity-check at https://github.com/runcycles

Cuts 354 → 206 lines (-42%) by collapsing overlapping sections. No
content removed in spirit; ~5 sections that all answered the same
question merged into one each.

What changed:
- "What is Cycles?" + "What is Runcycles?" + "Quick mental model" +
  "The ecosystem" → single "## What this is" section. A first-time
  reader doesn't need the same definition four ways.
- "Typical use cases" + "Who Runcycles is for" + "Where Runcycles fits"
  + "When to use Runcycles" → single "## Who it's for" section. Same
  reader question answered in one place.
- "## How it works" tightened — the diagram + Try-it snippets at the
  top already showed this; the section now references the diagram and
  states the loop in one sentence.
- "## What Runcycles enforces" converted from 5 sub-headings into a
  bulleted list. Same content, ~3x denser.
- "## Status" gained a CHANGELOG link so it's load-bearing instead of
  decorative.

What was dropped (deliberately):
- Mid-page "👉 Learn more: runcycles.io" CTA at line 131 — it sat
  before 220 more lines of content, reading as a false page-end.
- Web3 / EVM / "blockchain transactions" mentions in "Where Runcycles
  fits" + the defensive "Web3 is one surface area, not a requirement"
  one-liner. Not active product positioning; reads as holdover.
- Wrong docs URL on the old "Learn more" line (runcycles.github.io/docs
  → fixed to the canonical runcycles.io).

What was kept verbatim or near-verbatim:
- Top half (lines 1-130): badges, hook, value-prop bullets, CTA links,
  architecture diagram, GIF demo, Try-it MCP+Python snippets, full
  Start-here repo list. Untouched.
- "Why Runcycles exists" — distinct motivation, kept as-is (slightly
  tightened from 11 short lines to 2 paragraphs).
- "What Runcycles is not" — orthogonal differentiator, useful, kept.
- "Design principles" — short and load-bearing, kept verbatim.
@amavashev amavashev merged commit 5b964f7 into main May 2, 2026
3 checks passed
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.

1 participant