# Contributor Documentation Hub
Welcome to `docs/contributor/`—a curated knowledge base for new developers and contributors working on qsv. This folder gathers command deep-dives, quick references, architectural guides, and development patterns to help you ramp up quickly and contribute effectively across the codebase.
## Structure
Each major command has two companion documents:
- **Quick Reference** (`*_QUICK_REFERENCE.md`): TL;DR, key code entry points, architecture flow, performance highlights, and debugging tips.
- **Technical Guide** (`*_TECHNICAL_GUIDE.md`): Comprehensive exploration of design decisions, data structures, implementation strategies, performance optimizations, and extension points.
### Available Guides
| `stats` | [`STATS_QUICK_REFERENCE.md`](./STATS_QUICK_REFERENCE.md) | [`STATS_TECHNICAL_GUIDE.md`](./STATS_TECHNICAL_GUIDE.md) |
| `frequency` | [`FREQUENCY_QUICK_REFERENCE.md`](./FREQUENCY_QUICK_REFERENCE.md) | [`FREQUENCY_TECHNICAL_GUIDE.md`](./FREQUENCY_TECHNICAL_GUIDE.md) |
| `index` | [`INDEX_QUICK_REFERENCE.md`](./INDEX_QUICK_REFERENCE.md) | [`INDEX_TECHNICAL_GUIDE.md`](./INDEX_TECHNICAL_GUIDE.md) |
## About This Documentation
Most content in this directory is AI-generated or AI-assisted, created using tools such as GitHub Copilot, GPT-5, and Claude, with human review and refinement by project maintainers. We've found this approach accelerates documentation while keeping it synchronized with code changes.
**Treat this as living documentation**: If you find outdated sections, typos, clarifications needed, or gaps, please open a PR or issue. Fresh eyes catch details that slip through initial writing.
## What You'll Find Here
- **Command Guides**: Control flow explanations, data structure walkthroughs, performance trade-offs, and test strategies for individual commands.
- **Architecture Notes**: How commands interact with shared infrastructure (`Config`, indexing, stats caching) and why certain design choices were made.
- **Best Practices**: Rust patterns, unsafe code justification, performance optimization techniques, and common pitfalls to avoid.
- **Testing Patterns**: How to write tests, run the test suite, and debug failures specific to your changes.
- **Cross-References**: Direct links to relevant source files, test cases, and related docs to minimize context-switching.
## Getting Started
### For Bug Fixes or Minor Tweaks
1. Locate your command's quick reference to understand the architecture at a glance.
2. Scan the relevant test file (`tests/test_<command>.rs`) to see how the feature is tested.
3. Read the technical guide's relevant section for context on performance, safety, or design rationale.
4. Make your change and run tests: `cargo test --test test_<command> -- --test-threads=1`.
### For Larger Features or New Commands
1. Review the quick reference template and technical guide template (mirrored from existing commands).
2. Implement your feature and write comprehensive tests.
3. After implementation, create a quick reference and technical guide following the established structure.
4. Link them in the table of available guides above.
### Tips for Success
- **Read before writing**: The technical guides often explain *why* existing code is structured a certain way. Avoiding incompatible changes saves review cycles.
- **Follow Rust conventions**: Each guide includes relevant Rust concepts (ownership, unsafe blocks, trait usage). Align with the patterns shown.
- **Test frequently**: Run `cargo test --test test_<command>` after each meaningful change to catch regressions early.
- **Check the copilot-instructions**: Root-level `copilot-instructions.md` documents project-wide standards (latest Rust features, safety comments, performance expectations).
## Contributing Improvements
### Documentation Updates
- **Typos or clarifications**: File a quick PR with the fixes; these are always welcome.
- **Outdated sections**: If code has moved or APIs changed, update the corresponding guide and reference it in your commit message.
- **Missing examples**: Add concrete snippets or edge cases if they help illustrate tricky logic.
### New Command Documentation
When adding a new command or significant feature:
1. Create a quick reference following the template from `STATS_QUICK_REFERENCE.md`.
2. Expand it into a comprehensive technical guide following the template from `STATS_TECHNICAL_GUIDE.md`.
3. Link both files in the table above.
4. Include testing instructions so others can validate behavior.
### Improving Existing Guides
- Spotted a confusing section? Submit a clearer version.
- Found a missing edge case or performance consideration? Add it.
- Did you write a utility or pattern that other contributors should know? Document it.
All contributions—docs, code fixes, or discussions—help qsv grow stronger.
## Additional Resources
- **Project Overview**: See `docs/PROJECT_TECHNICAL_OVERVIEW.md` for an architectural helicopter view.
- **Performance Context**: `docs/PERFORMANCE.md` explains stats caching, benchmarks, and indexing benefits.
- **GitHub Wiki**: https://github.com/dathere/qsv/wiki for user-facing documentation and supplemental guides.
- **Issue Tracker**: https://github.com/dathere/qsv/issues for tracking bugs, feature requests, and discussions.
- **Copilot Instructions**: Root-level `copilot-instructions.md` for project standards and Rust patterns.
## Acknowledgments
This documentation owes much to AI-assisted generation (Copilot, GPT-5, Claude) paired with human oversight. The hybrid approach lets us scale knowledge capture without sacrificing accuracy. If you improve these docs, you're preserving that balance for the next contributor.
---
Thanks for investing in qsv's contributor experience. These docs get better with every iteration, and your feedback shapes them.