Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: restructure documentation into audience-based portals

Browse Source 
BREAKING CHANGE: Documentation URLs have changed

New structure:
- user/ - End-user documentation (device setup, sync guides, frontend)
- developer/ - Developer documentation (API reference, protocols, specs)
- operations/ - Operations documentation (deployment, troubleshooting)
- contributing/ - Contribution guides

Changes:
- Created portal INDEX.md files for each audience section
- Moved device guides to user/devices/ (kobo-setup.md, koreader-setup.md)
- Moved API docs to developer/ (api-reference.md, collections-api.md)
- Moved sync guide to user/sync-guide.md
- Moved troubleshooting to operations/troubleshooting.md
- Moved all split API docs to developer/api/
- Renamed protocol files (kobo-protocol.md, koreader-protocol.md)
- Added placeholder user guides (frontend, user-areas, settings, admin)
- Updated all internal links to new paths
- Updated Go code (http_handler.go, navigation.go) for new paths
- Updated main INDEX.md for audience-based navigation

Benefits:
- Clear separation of user and developer documentation
- Scalable structure for future user guide expansion
- Better organization and discoverability
- Audience-specific landing pages

Related to DOCS_IMPLEMENTATION_PLAN.md Phase 2 completion
This commit is contained in:
john-okeefe
2026-02-02 15:58:34 -05:00
parent ece90c0f1f
commit 253f56399d
76 changed files with 372 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/INDEX.md
+91 -183
View File
@@ -1,229 +1,137 @@
# Bookhoard Documentation Index
# Bookhoard Documentation
Complete guide to Bookhoard documentation. Find what you need quickly.
---
## 🚀 Quick Links
## 🚀 By Audience
### For New Users
1. [README.md](../README.md) - **Start here!** Project overview and quick start
2. [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Understanding and using sync
3. [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) - Kobo e-reader setup
4. [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md) - KOReader setup
### 👤 For End Users
### For Self-Hosting
1. [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Deployment and troubleshooting
2. [.env.example](../.env.example) - Secrets configuration (JWT and DB password)
**[User Documentation Portal](user/INDEX.md)** - Guides for using Bookhoard features
### For Contributors
1. [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Development workflow and architecture
2. [docs/API_REFERENCE.md](API_REFERENCE.md) - Complete API documentation
3. [docs/COLLECTIONS_API.md](COLLECTIONS_API.md) - Collections API
4. [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md) - WebSocket protocol
- **Device Setup**
- [Kobo Setup Guide](user/devices/kobo-setup.md) - Complete Kobo e-reader configuration
- [KOReader Setup Guide](user/devices/koreader-setup.md) - KOReader on Kindle/Kobo/PocketBook
- **Sync Configuration**
- [Universal Sync Guide](user/sync-guide.md) - Understanding sync, book matching, conflicts
- **Frontend & Settings** (Coming Soon)
- Frontend Guide
- User Areas Guide
- Settings Guide
- Admin Guide
### 👨‍💻 For Developers
**[Developer Documentation Portal](developer/INDEX.md)** - Technical documentation & API reference
- **API Documentation**
- [Complete API Reference](developer/api-reference.md) - Monolithic REST API reference (1,300+ lines)
- [Split Endpoint Docs](developer/api/INDEX.md) - Individual endpoints with interactive API Explorer
- [Collections API](developer/collections-api.md) - Collections management API
- **Protocol Specifications**
- [Kobo Sync Protocol](developer/api/sync/kobo-protocol.md) - Kobo device sync
- [KOReader Sync Protocol](developer/api/sync/koreader-protocol.md) - KOReader sync
- [WebSocket API](developer/websocket-api.md) - Real-time events
### 🔧 For Operations
**[Operations Documentation Portal](operations/INDEX.md)** - Deployment & maintenance
- **Deployment**
- [Troubleshooting Guide](operations/troubleshooting.md) - Common deployment issues and solutions
- **Maintenance** (Coming Soon)
- Deployment Guide
- Maintenance Guide
- Monitoring Guide
### 🤝 For Contributors
**[Contributing Portal](contributing/INDEX.md)** - Development workflow
- [Development Guide](contributing/DEVELOPMENT.md) - Architecture, setup, testing
- [PROJECT_GUIDELINES.md](PROJECT_GUIDELINES.md) - Development rules and standards
---
## 📚 Documentation by Topic
## 📚 Quick Links
### Getting Started
- **[README.md](../README.md)** - Project overview, features, quick start guide
- **[docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md)** - Development environment setup
### Deployment & Operations
- **[docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common deployment issues and solutions
- **[.env.example](../.env.example)** - Required secrets (JWT_SECRET, DBPASS)
- **[docker-compose.yml](../docker-compose.yml)** - Operational configuration with defaults
- **[Makefile](../Makefile)** - Build and test commands
### Using Sync Features
- **[docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)** - Universal sync user guide
- Understanding sync
- Book matching and auto-linking
- Conflict resolution
- Best practices
### Device Setup
- **[docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md)** - Kobo e-reader configuration
- Device registration
- Sync configuration
- OPDS wireless book delivery
- Troubleshooting
- **[docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)** - KOReader configuration
- Installation on Kindle/Kobo/PocketBook
- Sync setup
- OPDS catalog access
- Troubleshooting
### API Documentation
- **[docs/API_REFERENCE.md](API_REFERENCE.md)** - Complete REST API reference
- Authentication
- User management
- Libraries
- Media items
- Reading progress
- Notes & highlights
- Analytics
- Book matching
- OPDS
- Sync protocols (KOReader, Kobo)
- WebSocket
- **[docs/COLLECTIONS_API.md](COLLECTIONS_API.md)** - Collections API
- Create and manage collections
- Auto-assign rules
- Test rules
- Bulk operations
- Device shelf mappings
- **[docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md)** - WebSocket protocol
- Connection flow
- Message format
- Real-time sync broadcasts
- Authentication
### Contributing
- **[docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md)** - Development guide
- Architecture overview
- Directory structure
- Local development setup
- Testing guidelines
- Code style
- Deployment
- **[PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md)** - Development rules and standards
- Critical prohibitions
- Mandatory requirements
- Error recovery protocol
### Reference
- **[go.mod](../go.mod)** - Go dependencies
- **[database/schema/schema.sql](../database/schema/schema.sql)** - Database schema
- **[bruno/](../bruno/)** - API test collections
---
## 📖 Reading Path by Role
### Self-Hoster / End User
**Goal**: Set up and use Bookhoard for reading
1. Start with [README.md](../README.md) - Understand what Bookhoard is
2. Follow quick start in README.md to get running
3. Set up your device:
- Kobo: [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md)
- KOReader: [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)
4. Learn about sync: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
5. If issues arise: [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)
### Developer
**Goal**: Contribute to Bookhoard or integrate with it
1. Start with [README.md](../README.md) - Project overview
2. Read [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Architecture and setup
3. Review [docs/API_REFERENCE.md](API_REFERENCE.md) - API endpoints
4. Check [PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md) - Development rules
5. Explore codebase and contribute!
### API Integrator
**Goal**: Build integration with Bookhoard
1. Review [README.md](../README.md) - Feature overview
2. Study [docs/API_REFERENCE.md](API_REFERENCE.md) - All endpoints
3. Check specialized docs:
- Collections: [docs/COLLECTIONS_API.md](COLLECTIONS_API.md)
- WebSocket: [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md)
- Sync: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
4. Test with [bruno/](../bruno/) collections
| Want to... | Go to |
|------------|-------|
| **Get started** | [README.md](../README.md) - Project overview and quick start |
| **Set up a device** | [User Portal → Device Setup](user/INDEX.md) |
| **Use the API** | [Developer Portal → API Docs](developer/INDEX.md) |
| **Deploy Bookhoard** | [Operations Portal → Troubleshooting](operations/troubleshooting.md) |
| **Contribute code** | [Contributing Portal → Development Guide](contributing/DEVELOPMENT.md) |
| **Understand sync** | [User Portal → Sync Guide](user/sync-guide.md) |
---
## 🔍 Quick Find
### "How do I..."
| ...do this? | See this document |
|-------------|------------------|
| Question | Answer |
|----------|--------|
| ...install Bookhoard? | [README.md](../README.md) - Quick Start |
| ...set up my Kobo? | [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) |
| ...set up KOReader? | [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md) |
| ...understand sync? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) |
| ...resolve conflicts? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Managing Conflicts |
| ...match books? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Book Matching |
| ...troubleshoot deployment? | [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
| ...use the API? | [docs/API_REFERENCE.md](API_REFERENCE.md) |
| ...set up development? | [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) |
| ...contribute code? | [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Contributing |
| ...set up my Kobo? | [Kobo Setup Guide](user/devices/kobo-setup.md) |
| ...set up KOReader? | [KOReader Setup Guide](user/devices/koreader-setup.md) |
| ...understand sync? | [Sync Guide](user/sync-guide.md) |
| ...resolve conflicts? | [Sync Guide](user/sync-guide.md) - Managing Conflicts |
| ...troubleshoot deployment? | [Troubleshooting Guide](operations/troubleshooting.md) |
| ...use the API? | [API Reference](developer/api-reference.md) |
| ...contribute code? | [Development Guide](contributing/DEVELOPMENT.md) |
### "Where is..."
| ...this information? | See this document |
|-------------------|------------------|
| Information | Location |
|-------------|----------|
| ...features list? | [README.md](../README.md) |
| ...database schema? | [database/schema/schema.sql](../database/schema/schema.sql) |
| ...API endpoints? | [docs/API_REFERENCE.md](API_REFERENCE.md) |
| ...API endpoints? | [API Reference](developer/api-reference.md) |
| ...secrets config? | [.env.example](../.env.example) |
| ...operational config? | [docker-compose.yml](../docker-compose.yml) |
| ...deployment issues? | [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
| ...deployment issues? | [Troubleshooting Guide](operations/troubleshooting.md) |
---
## 📊 Documentation Statistics
| File | Lines | Purpose | Audience |
|------|-------|---------|----------|
| README.md | 150 | Overview & quick start | Everyone |
| contributing/DEVELOPMENT.md | 450 | Development workflow | Contributors |
| API_REFERENCE.md | 1,300+ | Complete REST API | Developers, integrators |
| COLLECTIONS_API.md | 494 | Collections API | Developers, integrators |
| SYNC_USER_GUIDE.md | 350+ | Sync usage guide | End users |
| TROUBLESHOOTING.md | 300 | Deployment troubleshooting | Self-hosters |
| KOBO_SETUP.md | 598 | Kobo setup | Kobo users |
| KOREADER_SETUP.md | 504 | KOReader setup | KOReader users |
| WEBSOCKET_API.md | 676 | WebSocket protocol | Developers |
| PROJECT_GUIDELINES.md | 250 | Development rules | Developers |
**Total**: ~5,000 lines of comprehensive documentation
---
## 🎯 Common Tasks
## 🎯 Common Workflows
### Set up a new device
1. Device setup guide: [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) or [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)
2. Sync overview: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
3. Troubleshooting: Device-specific setup guides
### Troubleshoot sync issues
1. Check [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - "Managing Conflicts" and "Best Practices"
2. Review device-specific guide for common issues
3. Check [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) for general issues
1. Choose your device: [Kobo](user/devices/kobo-setup.md) or [KOReader](user/devices/koreader-setup.md)
2. Understand sync: [Sync Guide](user/sync-guide.md)
3. Troubleshoot: Device-specific guides
### Integrate with Bookhoard API
1. Start with [docs/API_REFERENCE.md](API_REFERENCE.md) - Complete API reference
2. Check [docs/COLLECTIONS_API.md](COLLECTIONS_API.md) for collections
3. Review [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md) for real-time updates
4. Use [bruno/](../bruno/) test collections as examples
1. Start with [API Reference](developer/api-reference.md)
2. Explore [Collections API](developer/collections-api.md)
3. Review [WebSocket API](developer/websocket-api.md)
4. Test with [bruno/](../bruno/) collections
### Deploy to production
1. Follow [README.md](../README.md) quick start
2. Configure environment: [.env.example](../.env.example)
3. Review [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
4. Check [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) for performance tuning
3. Review [Troubleshooting Guide](operations/troubleshooting.md)
4. Check [Development Guide](contributing/DEVELOPMENT.md) for performance tuning
---
## 📝 Contributing to Documentation
When adding new features:
1. Update [README.md](../README.md) - Add to features list if user-facing
2. Update [docs/API_REFERENCE.md](API_REFERENCE.md) - Document new endpoints
3. Add/update tests in [bruno/](../bruno/)
4. Update relevant guides (SYNC_USER_GUIDE.md, device guides, etc.)
5. Keep [PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md) in mind
1. **User-facing features** → Update relevant User docs
2. **API endpoints** → Update [API Reference](developer/api-reference.md) & split docs
3. **Backend changes** → Update [Development Guide](contributing/DEVELOPMENT.md)
4. **Deployment changes** → Update [Operations Portal](operations/INDEX.md)
Keep [PROJECT_GUIDELINES.md](PROJECT_GUIDELINES.md) in mind for documentation standards.
---
**Last Updated**: 2026-02-01
**Last Updated**: 2026-02-02
**Bookhoard Version**: 1.0