docs: refactor README + landing page (heavy slim)#284
Merged
Conversation
Critical review found four big problems:
- README.md was 1527 lines — same value-prop messaging repeated 4-5 times
(tagline → What is → Why → Problem → Solution), Use Cases section
duplicated, the entire 933-line Command Reference was a copy of
docs/reference/index.html.
- docs/index.html had 22 feature cards laid out flat — no priority,
scroll fatigue, mega-cap features (Bitbucket, Stacked PRs) shown at
the same visual weight as ship.draft defaults.
- AI agent messaging took ~30% of README, risking miscategorization as
an "AI tool" when most users are general developers.
- The "What's New in v0.4" section in the guide was version-specific —
same problem will recur for v0.5, v0.6.
Changes
-------
README.md (1527 → 204 lines)
- New tagline: "From ticket to PR. One command."
- Single demo block (no repeats), 60-second tour, Top 6 features,
comparison table, error code matrix, doc links.
- Removed: duplicated Use Cases section, full Command Reference (now
linked to docs/reference/), AI Token Efficiency / Before-After
expansion, redundant Why/Problem/Solution sections.
docs/index.html (22 cards → 6 featured cards + collapsible "More features")
- 6 consolidated cards: Ticket-driven worktrees · Stacked PRs · Multi-
forge & multi-CI · One-step ship + lifecycle · Built for agents ·
Build cache + ergonomics.
- Remaining 16 features compressed into a `<details>` block — visible
on demand, no scroll fatigue, all features still discoverable.
- AI agent messaging consolidated to one card ("Built for agents")
covering --json, JSONL, error codes, offline, headless, schemastore.
docs/guide/index.html — "What's New in v0.4" section renamed to
"Recipes & Examples" with a permanent home; future versions can keep
adding recipes here without further renames.
All HTML validated (depth balanced). README links to docs/{guide,reference}
verified. The release workflow's docs snapshot will pick this up on next
release.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Extends the docs refactor with discovery layer improvements aimed at
both classic search engines and modern answer engines (Anthropic /
OpenAI / Perplexity / Google AI).
AEO (Answer Engine Optimization)
--------------------------------
- New `docs/llms.txt` (3.5 KB) — emerging standard for LLM crawlers.
Concise project summary with key facts (latest version, install,
auth, config, error codes, comparisons), structured for clean LLM
ingestion.
- New `docs/llms-full.txt` (13 KB) — comprehensive plain-text dump
covering all 27 commands, configuration, auth, error codes, stacked
PRs, multi-forge support, observability, FAQ. One-stop file for any
LLM/agent that needs the full picture.
- `docs/robots.txt` explicitly welcomes GPTBot, ChatGPT-User,
ClaudeBot, anthropic-ai, PerplexityBot, Google-Extended, CCBot.
- Added `<link rel="alternate" type="text/plain" href="/llms.txt">`
on every page so crawlers can discover the LLM-friendly variants.
Structured data (Schema.org JSON-LD)
------------------------------------
docs/index.html now emits 4 JSON-LD blocks:
1. SoftwareApplication — bumped to v0.4.0, datePublished 2026-05-04,
softwareRequirements, releaseNotes URL, screenshot URL,
applicationSubCategory, expanded keywords (Bitbucket, JSONL, etc.)
2. HowTo — 5-step "60-second tour" (start → switch → commit → ship →
ci/merge) so Google can render a HowTo carousel and AI engines
can answer "how do I use parsec".
3. BreadcrumbList — supports Google sitelinks.
4. FAQPage — expanded from 10 → 18 Q&As with v0.4-specific entries
(Bitbucket, offline, observability JSONL, compress, config schema,
forges/CI, build cache).
docs/guide/index.html — TechArticle + BreadcrumbList (replaces the
two stale duplicate JSON-LD blocks that existed lower in the file).
docs/reference/index.html — TechArticle + BreadcrumbList (same
cleanup of duplicate blocks).
Social / SEO meta polish
------------------------
- og:image + twitter:image (demo.gif as fallback) — previously absent;
social shares now show a preview.
- og:image:width / height / alt, og:locale, og:site_name on all pages.
- Page titles tightened with primary keywords:
- index: "From ticket to PR. One command. | Git worktree lifecycle…"
- guide: "Getting Started Guide — git-parsec | Install, configure,
ship in 5 minutes"
- reference: "Command Reference — git-parsec | All 27 commands…"
- Descriptions rewritten to surface v0.4 differentiators (Bitbucket,
stacked PRs, JSONL observability) while staying under 160 chars.
- robots meta with max-snippet/max-image-preview/max-video-preview
signals for richer SERP rendering.
Sitemap
-------
- All `lastmod` dates bumped from 2026-04-22 → 2026-05-04 to trigger
re-crawl.
- llms.txt and llms-full.txt added to sitemap with priority 0.7.
Validation
----------
- All 3 HTML pages parse with balanced depth.
- All 8 JSON-LD blocks (4 + 2 + 2) parse as valid JSON, types verified.
- Local server confirms files served with correct MIME types.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
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
1 participant
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.
Heavy refactor of README.md and docs/index.html based on a critical info-architecture review.
Why
What
README.md— 1527 → 204 linesdocs/index.html— 22 cards → 6 featured + collapsible<details><details>블록 안에 grid로 정리 — 클릭 시 펼쳐짐, 스크롤 피로 0docs/guide/index.htmlDiff stats
```
README.md | 1553 ++++--------------
docs/guide/index.html | 10 +-
docs/index.html | 283 ++--------
3 files changed, 182 insertions(+), 1664 deletions(-)
```
Verification
python3 -m http.server 8765confirms 6 featured cards + 1 `more-features` block render correctlyNotes
🤖 Generated with Claude Code