Skip to content

docs(readme): refresh opening, add Features + Status, sharpen comparison#96

Merged
allmonday merged 1 commit into
masterfrom
docs/readme-refresh
Jul 1, 2026
Merged

docs(readme): refresh opening, add Features + Status, sharpen comparison#96
allmonday merged 1 commit into
masterfrom
docs/readme-refresh

Conversation

@allmonday

Copy link
Copy Markdown
Collaborator

Summary

README 感觉有点单薄,这版按之前讨论的优先级做了 5 处补强(截图那条留作后续——需要先跑 demo)。

改动

  1. 开篇加问题陈述:原 hero 后直接跳到 mermaid 图,读者不知道在解决什么痛点。补一段"传统全栈要把一个 domain 拆成 5 份文件",把"manual"的含义提前讲清楚。

  2. 新增 Features 区块:从 docs/feature-highlights.md 抽 5 条最锋利的差异化点(N+1 自动消除 / 选择贯穿全栈 / 超越 ORM 的关系 / 一种 service 多传输 / AI-agent-first MCP),README 之前完全没有体现这块。

  3. Quick Start Step 1 给具体 N+1 数字:原来只说"恰好两次 SQL 往返",没有规模感。补一句"100 个 user × 各 10 篇 post,仍然是 2 次查询,不是 101 次"——一句数字胜过对勾。

  4. Comparison table 扩充 + 公平评价

    • 新增 2 行(SQL column pruning、Same code → GraphQL+REST+MCP)—— 这是 nexusx 真正独有的差异点。
    • 把空泛的 "manual" 改成具体代价("manual DataLoader per relation"、"hand-written resolver per relation"、"one handler per endpoint")。
    • 表后加一段承认 Strawberry 和 FastMCP 各自强在哪,把 nexusx 定位成 tradeoff 而不是 silver bullet。
  5. 新增 Status 区块:PyPI 已经标了 Development Status :: 3 - Alpha,README 之前完全没说采用风险。一句话让读者知道是 alpha,API 可能变。

没做的

  • 截图/GIF:GraphiQL、Voyager、Swagger 三张图是 README 最大的视觉缺口,但要跑起来才能截。建议单独开个 issue。
  • TOC:长度还不到需要 TOC 的程度。
  • DB 驱动安装说明:小到可以后续随手补。

Test plan

  • 通读 README,确认叙述顺序自然
  • 检查 Features 5 条是否与 feature-highlights.md 的实际实现匹配
  • Comparison table 的具体措辞("manual DataLoader per relation" 等)确认公平且准确

🤖 Generated with Claude Code

Address the "thin README" feedback by:
- Open with a problem statement (5-file split) instead of jumping straight to mermaid
- Add a Features section with 5 differentiated bullets pulled from feature-highlights.md
- Make the N+1 pitch concrete (100 users × 10 posts → still 2 queries, not 101)
- Expand comparison table with 2 more dimensions (SQL pruning, multi-transport) and replace glib "manual" cells with specific costs
- Add a paragraph crediting Strawberry / FastMCP where they shine, framing nexusx as a tradeoff
- Add Status section so readers know it's alpha before adopting

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@allmonday allmonday merged commit 85d7f27 into master Jul 1, 2026
1 check 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