Skip to content

Commit 46e2328

Browse files
committed
docs: apply awesome-readme best practices
Major README improvements based on analysis of top-tier README examples (size-limit, ky) and awesome-readme repository. ## Changes Applied ### 1. Problem-Solution Opening โœจ **Before**: Generic tagline **After**: Problem โ†’ Solution framing - Identifies pain point (commands in isolation) - Shows consequence (freeze in real codebase) - Presents solution (workflow training) ### 2. Quick Links Section ๐Ÿ”— Added prominent navigation after header: - Download, Quick Start, Features, Docs, Issues, Contributing - Single click to key sections - Reduces time-to-action ### 3. Consolidated Features Section โœจ **Before**: Features scattered across multiple sections **After**: Single scannable list with 8 key features - Smart Learning (FSRS) - Daily Quests - Progress Tracking - Offline & Private - Real Helix Accuracy - 31 Commands - Gamification - 20 Scenarios ### 4. Improved Badges ๐Ÿ“Š - Added CI Status badge (shows build health) - Removed Edition badge (too technical) - Kept License and Rust version (essential) ### 5. Code Example with Real Output ๐Ÿ’ป Added visual example of training session: - Shows actual TUI interface - Demonstrates quest progress - Shows XP and level system - Makes value prop tangible ### 6. Extracted CONTRIBUTING.md ๐Ÿ“ **Before**: 92 lines in README **After**: Compact summary (11 lines) + full CONTRIBUTING.md (104 lines) - Cleaner main README - Better for contributors (dedicated file) - Follows GitHub conventions ### 7. Fixed Details/Summary Structure ๐Ÿ”ง **Before**: <details><summary><h2>Title</h2></summary> **After**: ## Title\n<details><summary>Click to expand</summary> - Preserves visual hierarchy - Headings always visible - Better GitHub rendering ## Impact **Readability**: - โœ… Problem-solution hook (30 sec to 'aha' moment) - โœ… Quick Links (instant navigation) - โœ… Visual example (shows, not tells) - โœ… Scannable features (5 sec to understand value) **Before**: 565 lines, philosophy-first, no examples **After**: 599 lines, value-first, visual examples **Structure**: - Hook โ†’ Features โ†’ Quick Start โ†’ Details - Show โ†’ Tell โ†’ Deep Dive - Problem โ†’ Solution โ†’ How To Use ## Inspiration Based on analysis of: - awesome-readme repository - size-limit (problem-solution framing, social proof) - ky (minimalist badges, code examples) ## Files - README.md: Optimized main documentation - CONTRIBUTING.md: Extracted contribution guidelines Analysis saved in .local/README_IMPROVEMENTS.md
1 parent b0569ec commit 46e2328

File tree

3 files changed

+233
-356
lines changed

3 files changed

+233
-356
lines changed

0 commit comments

Comments
ย (0)