Skip to content

Commit 2aab70f

Browse files
Vswaroop04Vswaroop04
committed
📝 docs(docs): update documentation structure and content
1 parent 565f87a commit 2aab70f

17 files changed

+1718
-22
lines changed

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ mypy git_quick
6060

6161
## Commit Messages
6262

63+
Btw you can also use the same tool for commit msgs as well :>
6364
We follow [Conventional Commits](https://www.conventionalcommits.org/):
6465

6566
```

‎DOCUMENTATION_STRUCTURE.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# Documentation Structure
2+
3+
This document explains the organization of git-quick's documentation.
4+
5+
## 📁 Structure Overview
6+
7+
### Root Directory (Essential Files Only)
8+
```
9+
git-quick/
10+
├── README.md # Project overview & quick links
11+
├── QUICKSTART.md # 5-minute getting started guide
12+
├── CONTRIBUTING.md # How to contribute
13+
└── LICENSE # MIT license
14+
```
15+
16+
**Purpose**: Keep the root clean with only the most essential files that users need immediately.
17+
18+
### docs/ Directory (All Documentation)
19+
```
20+
docs/
21+
├── README.md # Documentation index & navigation
22+
├── INSTALLATION.md # Installation instructions
23+
├── USAGE.md # Complete command reference
24+
├── QUICK_REFERENCE.md # Command cheat sheet
25+
├── AI_INTEGRATION.md # AI features deep dive
26+
├── FIRST_RUN_EXPERIENCE.md # First-time user guide
27+
├── SETUP.md # Development setup
28+
│
29+
├── setup/ # Setup & Configuration
30+
│ ├── AI_SETUP.md # AI provider configuration
31+
│ ├── CONFIGURATION_GUIDE.md # All config options
32+
│ └── SETUP_WIZARD_IMPROVEMENTS.md # Setup wizard docs
33+
│
34+
└── development/ # Development Documentation
35+
├── PROJECT_SUMMARY.md # Architecture overview
36+
├── PUBLISHING.md # Release process
37+
├── DISTRIBUTION_SUMMARY.md # Multi-platform distribution
38+
├── NEW_CLI_STRUCTURE.md # CLI architecture
39+
└── UNIFIED_CLI_SUMMARY.md # CLI design decisions
40+
```
41+
42+
## 🎯 Documentation Categories
43+
44+
### 1. User Documentation (Root & docs/)
45+
**For end users who want to use git-quick**
46+
47+
- **README.md** - First thing users see, project overview
48+
- **QUICKSTART.md** - Get started in 5 minutes
49+
- **docs/INSTALLATION.md** - How to install
50+
- **docs/USAGE.md** - How to use all commands
51+
- **docs/QUICK_REFERENCE.md** - Quick command lookup
52+
53+
### 2. Setup Documentation (docs/setup/)
54+
**For users configuring git-quick**
55+
56+
- **AI_SETUP.md** - Configure Ollama, OpenAI, or Anthropic
57+
- **CONFIGURATION_GUIDE.md** - All configuration options
58+
- **SETUP_WIZARD_IMPROVEMENTS.md** - How the wizard works
59+
60+
### 3. Development Documentation (docs/development/)
61+
**For contributors and maintainers**
62+
63+
- **PROJECT_SUMMARY.md** - Architecture and design
64+
- **PUBLISHING.md** - How to publish releases
65+
- **DISTRIBUTION_SUMMARY.md** - Multi-platform packaging
66+
- **NEW_CLI_STRUCTURE.md** - CLI implementation
67+
- **UNIFIED_CLI_SUMMARY.md** - CLI design rationale
68+
69+
### 4. Contributing (Root)
70+
**For potential contributors**
71+
72+
- **CONTRIBUTING.md** - Contribution guidelines
73+
74+
## 🗺️ Navigation Paths
75+
76+
### New User Journey
77+
```
78+
1. README.md (overview)
79+
↓
80+
2. QUICKSTART.md (get started)
81+
↓
82+
3. docs/INSTALLATION.md (install)
83+
↓
84+
4. docs/setup/AI_SETUP.md (configure AI)
85+
↓
86+
5. docs/USAGE.md (learn commands)
87+
```
88+
89+
### Configuration Journey
90+
```
91+
1. docs/setup/AI_SETUP.md (choose provider)
92+
↓
93+
2. docs/setup/CONFIGURATION_GUIDE.md (customize)
94+
↓
95+
3. docs/FIRST_RUN_EXPERIENCE.md (what to expect)
96+
```
97+
98+
### Contributor Journey
99+
```
100+
1. CONTRIBUTING.md (guidelines)
101+
↓
102+
2. docs/SETUP.md (dev setup)
103+
↓
104+
3. docs/development/PROJECT_SUMMARY.md (architecture)
105+
↓
106+
4. docs/development/PUBLISHING.md (releases)
107+
```
108+
109+
## 📋 File Purpose Reference
110+
111+
| File | Audience | Purpose |
112+
|------|----------|---------|
113+
| README.md | Everyone | Project overview, quick links |
114+
| QUICKSTART.md | New users | Fast onboarding |
115+
| CONTRIBUTING.md | Contributors | How to contribute |
116+
| docs/README.md | Everyone | Documentation index |
117+
| docs/INSTALLATION.md | Users | Installation guide |
118+
| docs/USAGE.md | Users | Command reference |
119+
| docs/QUICK_REFERENCE.md | Users | Quick lookup |
120+
| docs/AI_INTEGRATION.md | Users | AI features |
121+
| docs/FIRST_RUN_EXPERIENCE.md | New users | First-run guide |
122+
| docs/SETUP.md | Developers | Dev environment |
123+
| docs/setup/AI_SETUP.md | Users | AI configuration |
124+
| docs/setup/CONFIGURATION_GUIDE.md | Users | All config options |
125+
| docs/setup/SETUP_WIZARD_IMPROVEMENTS.md | Developers | Wizard internals |
126+
| docs/development/PROJECT_SUMMARY.md | Developers | Architecture |
127+
| docs/development/PUBLISHING.md | Maintainers | Release process |
128+
| docs/development/DISTRIBUTION_SUMMARY.md | Maintainers | Packaging |
129+
| docs/development/NEW_CLI_STRUCTURE.md | Developers | CLI design |
130+
| docs/development/UNIFIED_CLI_SUMMARY.md | Developers | CLI rationale |
131+
132+
## 🔍 Finding Documentation
133+
134+
### "I want to..."
135+
136+
- **...install git-quick** → `docs/INSTALLATION.md`
137+
- **...get started quickly** → `QUICKSTART.md`
138+
- **...configure AI** → `docs/setup/AI_SETUP.md`
139+
- **...change settings** → `docs/setup/CONFIGURATION_GUIDE.md`
140+
- **...learn commands** → `docs/USAGE.md`
141+
- **...contribute code** → `CONTRIBUTING.md`
142+
- **...understand architecture** → `docs/development/PROJECT_SUMMARY.md`
143+
- **...publish a release** → `docs/development/PUBLISHING.md`
144+
145+
## 📝 Documentation Principles
146+
147+
### 1. Keep Root Clean
148+
- Only essential files in root directory
149+
- Everything else goes in `docs/`
150+
151+
### 2. Organize by Audience
152+
- User docs in `docs/`
153+
- Setup docs in `docs/setup/`
154+
- Dev docs in `docs/development/`
155+
156+
### 3. Clear Navigation
157+
- Every doc has clear purpose
158+
- `docs/README.md` provides navigation
159+
- Main `README.md` links to key docs
160+
161+
### 4. Progressive Disclosure
162+
- Quick start for beginners
163+
- Detailed guides for advanced users
164+
- Technical docs for developers
165+
166+
## 🔄 Maintenance
167+
168+
### Adding New Documentation
169+
170+
1. **User documentation** → Add to `docs/`
171+
2. **Setup/config documentation** → Add to `docs/setup/`
172+
3. **Development documentation** → Add to `docs/development/`
173+
4. **Update** `docs/README.md` with link
174+
5. **Update** main `README.md` if essential
175+
176+
### Updating Documentation
177+
178+
1. Keep file in same location
179+
2. Update cross-references if needed
180+
3. Update `docs/README.md` if title changes
181+
182+
### Removing Documentation
183+
184+
1. Remove file
185+
2. Update `docs/README.md`
186+
3. Update any cross-references
187+
4. Check for broken links
188+
189+
## ✅ Benefits of This Structure
190+
191+
### For Users
192+
✅ Easy to find what they need
193+
✅ Not overwhelmed by dev docs
194+
✅ Clear learning path
195+
196+
### For Contributors
197+
✅ Dev docs separate from user docs
198+
✅ Easy to find technical information
199+
✅ Clear contribution guidelines
200+
201+
### For Maintainers
202+
✅ Clean root directory
203+
✅ Organized documentation
204+
✅ Easy to maintain and update
205+
206+
## 📊 Before vs After
207+
208+
### Before (Cluttered Root)
209+
```
210+
git-quick/
211+
├── README.md
212+
├── AI_SETUP.md
213+
├── CONFIGURATION_GUIDE.md
214+
├── CONTRIBUTING.md
215+
├── DISTRIBUTION_SUMMARY.md
216+
├── PROJECT_SUMMARY.md
217+
├── PUBLISHING.md
218+
├── QUICKSTART.md
219+
├── QUICK_REFERENCE.md
220+
├── SETUP_WIZARD_IMPROVEMENTS.md
221+
├── NEW_CLI_STRUCTURE.md
222+
├── UNIFIED_CLI_SUMMARY.md
223+
└── docs/
224+
├── AI_INTEGRATION.md
225+
├── FIRST_RUN_EXPERIENCE.md
226+
├── INSTALLATION.md
227+
├── SETUP.md
228+
└── USAGE.md
229+
```
230+
**Problem**: 12 markdown files in root, hard to navigate
231+
232+
### After (Organized)
233+
```
234+
git-quick/
235+
├── README.md
236+
├── QUICKSTART.md
237+
├── CONTRIBUTING.md
238+
└── docs/
239+
├── README.md (navigation hub)
240+
├── [5 user docs]
241+
├── setup/ (3 setup docs)
242+
└── development/ (5 dev docs)
243+
```
244+
**Solution**: 3 files in root, everything else organized in docs/
245+
246+
## 🎯 Summary
247+
248+
The documentation is now organized into:
249+
- **Root**: Essential files only (README, QUICKSTART, CONTRIBUTING)
250+
- **docs/**: All user documentation
251+
- **docs/setup/**: Setup and configuration guides
252+
- **docs/development/**: Development and maintenance docs
253+
254+
This structure makes it easy for users to find what they need without being overwhelmed by development documentation.

‎README.md‎

Lines changed: 59 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ npm install -g git-quick-cli
1717
pip install git-quick
1818
```
1919

20+
**First Run:** git-quick will automatically guide you through AI setup on first use!
21+
2022
[See all installation options →](docs/INSTALLATION.md)
2123

2224
## Features
@@ -53,14 +55,30 @@ pip install git-quick
5355

5456
## Installation
5557

56-
### npm (Cross-platform)
58+
### Quick Install (Works immediately with smart fallback)
59+
5760
```bash
61+
# npm (All platforms)
5862
npm install -g git-quick-cli
63+
64+
# pip (Python)
65+
pip install git-quick
5966
```
6067

61-
### pip (Python)
68+
**Note:** git-quick works immediately after installation! It uses intelligent commit message generation based on your changes. For AI-powered messages, optionally install Ollama (see below).
69+
70+
### Optional: AI-Powered Messages (Ollama)
71+
72+
For enhanced AI commit messages, install Ollama (free, runs locally):
73+
6274
```bash
63-
pip install git-quick
75+
# macOS/Linux
76+
curl -fsSL https://ollama.ai/install.sh | sh
77+
78+
# Or visit: https://ollama.ai/download
79+
80+
# Pull a model
81+
ollama pull llama3
6482
```
6583

6684
### From Source
@@ -70,23 +88,52 @@ cd git-quick
7088
pip install -e .
7189
```
7290

73-
**See [Installation Guide](docs/INSTALLATION.md) for detailed instructions, including Windows setup.**
91+
**See [Installation Guide](docs/INSTALLATION.md) for detailed instructions.**
92+
93+
## 📚 Documentation
94+
95+
- **[Quick Start](QUICKSTART.md)** - Get started in 5 minutes
96+
- **[Installation](docs/INSTALLATION.md)** - Platform-specific installation
97+
- **[AI Setup](docs/setup/AI_SETUP.md)** - Configure AI providers
98+
- **[Configuration](docs/setup/CONFIGURATION_GUIDE.md)** - All configuration options
99+
- **[Usage Guide](docs/USAGE.md)** - Complete command reference
100+
- **[Contributing](CONTRIBUTING.md)** - How to contribute
101+
102+
**[📖 View All Documentation →](docs/README.md)**
74103

75104
## Quick Start
76105

77106
```bash
78-
# Quick commit and push with AI message
107+
# First time: Run setup wizard
108+
git-quick --setup
109+
110+
# Or just run git-quick and it will prompt you automatically
79111
git-quick
80112

81-
# See your commit story
82-
git-story
113+
# Other commands
114+
git-story # See your commit story
115+
git-time report # Track your time
116+
git-sync-all # Sync all branches
117+
```
83118

84-
# Track your time
85-
git-time report
119+
### First-Time Setup
86120

87-
# Sync all branches
88-
git-sync-all
89-
```
121+
On your first run, git-quick will ask you to choose an AI provider:
122+
123+
1. **Ollama** (Recommended) - Free, local, private AI
124+
- Automatically installs and downloads model
125+
- No API keys needed
126+
127+
2. **OpenAI** - Best quality, requires API key
128+
- Enter your API key when prompted
129+
130+
3. **Anthropic (Claude)** - Great for technical commits
131+
- Enter your API key when prompted
132+
133+
4. **No AI** - Smart fallback mode
134+
- Works immediately, no setup needed
135+
136+
You can always reconfigure later with `git-quick --setup`
90137

91138
## Configuration
92139

0 commit comments

Comments
 (0)