docs: improve project documentation for a clearer public surface (#634)

* docs: polish project documentation for a clearer public surface

Rewrite the README and supporting docs for a more professional first
impression: less emoji and badge noise, install-first structure, and a
real documentation index. Add a Contributor Covenant, tighten SECURITY
and GitHub templates, and make distro/update guides read as product docs
instead of internal status notes.

* docs: split install guide and add changelog plus support pages

Break INSTALL.md into a short primary guide, manual/PyPI package lists,
and troubleshooting. Add root CHANGELOG.md and SUPPORT.md, wire them
into the docs index and README, and drop the outdated screenshot lag note
now that v0.15 assets are on main.

* docs: humanize PR copy and remove em dashes

Strip em/en dashes from the documentation rewritten in this PR, fix
mid-sentence colon fallout from that pass, and smooth a few stiff
phrases so the public docs read more natural.

* docs: list Faster Whisper after rebase onto main

Installer and CLI already accept faster_whisper. Document it next to
the other engines, drop the outdated screenshot lag note, and keep the
on-device wording honest for local vs remote.
This commit is contained in:
Jatin K Malik
2026-09-07 22:51:14 -07:00
committed by GitHub
parent cdfe541c25
commit f48bdda525
20 changed files with 1420 additions and 2189 deletions
+35 -25
View File
@@ -1,42 +1,52 @@
---
name: Bug Report
about: Report a bug to help us improve Vocalinux
about: Report a bug to help improve Vocalinux
title: "[BUG] "
labels: bug
assignees: ''
---
## 🐛 Bug Description
A clear and concise description of what the bug is.
## Bug description
## 📋 Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. Speak '...'
4. See error
A clear description of what went wrong.
## ✅ Expected Behavior
A clear and concise description of what you expected to happen.
## Steps to reproduce
## ❌ Actual Behavior
What actually happened.
1.
2.
3.
## 📸 Screenshots
If applicable, add screenshots to help explain your problem.
## Expected behavior
## 💻 Environment
- **OS**: [e.g., Ubuntu 24.04]
- **Python Version**: [e.g., 3.12]
- **Vocalinux Version**: [e.g., 0.2.0-alpha]
- **Display Server**: [X11 / Wayland]
- **Speech Engine**: [VOSK / Whisper]
- **Model Size**: [small / medium / large]
What you expected to happen.
## Actual behavior
What happened instead.
## Screenshots
If applicable, attach screenshots.
## Environment
- **OS / distro**: (e.g. Ubuntu 24.04)
- **Python version**: (e.g. 3.12; 3.11+ required)
- **Vocalinux version**: (`vocalinux --version`)
- **Install method**: (installer / AppImage / AUR / Flatpak / Snap / source / PyPI)
- **Display server**: (X11 / Wayland)
- **Desktop environment**: (e.g. GNOME, KDE Plasma)
- **Speech engine**: (whisper_cpp / whisper / vosk / parakeet / remote_api)
- **Model**: (e.g. tiny, medium.en-q5_0, v3-european)
## Debug logs
Run `vocalinux --debug` and paste the relevant output:
## 📋 Debug Logs
Run `vocalinux --debug` and paste relevant log output:
```
[paste logs here]
```
## 📝 Additional Context
Add any other context about the problem here.
## Additional context
Anything else that might help (recent upgrade, Bluetooth mic, multi-GPU, etc.).
+18 -17
View File
@@ -6,26 +6,27 @@ labels: enhancement
assignees: ''
---
## 🚀 Feature Description
A clear and concise description of the feature you'd like.
## Feature description
## 💡 Problem Statement
Is your feature request related to a problem? Please describe.
Example: "I'm always frustrated when [...]"
What you would like Vocalinux to do.
## 📋 Proposed Solution
Describe the solution you'd like. Be as detailed as possible.
## Problem
## 🔄 Alternatives Considered
Describe any alternative solutions or features you've considered.
What is hard or missing today? Who is affected?
## 📸 Mockups / Examples
If applicable, add mockups, screenshots, or examples from other applications.
## Proposed solution
## 📝 Additional Context
Add any other context about the feature request here.
How you imagine it working (as specific as you can).
## ✅ Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
## Alternatives considered
Other approaches or tools you already tried.
## Mockups / examples
Links, screenshots, or references to similar apps (optional).
## Acceptance criteria
- [ ]
- [ ]
+19 -18
View File
@@ -1,33 +1,34 @@
## Description
<!-- Describe your changes in detail -->
<!-- What changed and why. Link design docs or discussions if relevant. -->
## Related Issue
## Related issue
<!-- Link to the related issue if applicable -->
<!-- Link the issue this closes, if any. -->
Fixes #
## Type of Change
## Type of change
- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
- [ ] ✨ New feature (non-breaking change which adds functionality)
- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to change)
- [ ] 📖 Documentation update
- [ ] 🧹 Code refactoring
- [ ] ✅ Test update
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation
- [ ] Refactor
- [ ] Tests
- [ ] Packaging / CI
## Checklist
- [ ] My code follows the code style of this project (black, isort)
- [ ] I have updated the documentation accordingly
- [ ] I have added tests to cover my changes
- [ ] All new and existing tests pass locally
- [ ] Pre-commit hooks pass
- [ ] Code follows project style (Black, isort, flake8)
- [ ] Documentation updated when user-facing behavior or install steps change
- [ ] Tests added or updated for the change
- [ ] Local tests pass (`pytest`)
- [ ] Conventional commit message style
## Screenshots (if applicable)
<!-- Add screenshots to help explain your changes -->
<!-- UI changes: before/after if helpful -->
## Additional Notes
## Notes for reviewers
<!-- Add any additional notes for reviewers -->
<!-- Anything not obvious from the diff -->