Commit 46e2328
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.md1 parent b0569ec commit 46e2328
3 files changed
+233
-356
lines changed
0 commit comments