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

docs: Update PROJECT_GUIDELINES documentation section

Browse Source 
Update Documentation section to reflect new docs/ structure:
- Add comprehensive documentation location table
- Clarify when to use docs/ vs README.md
- Include workflow for documentation updates
- Update all checklist sections with documentation guidance

Changes:
- README.md: Setup/onboarding only
- docs/: User-facing features and workflows
- docs/api/: API reference and endpoints
- docs/devices/: Device setup guides
- docs/contributing/: Development documentation

Ensures documentation is properly organized and searchable
via the new docs system with Lunr.js search.
This commit is contained in:
john-okeefe
2026-02-02 10:38:00 -05:00
parent 3babfe520f
commit a3709dc38a
1 changed files with 53 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PROJECT_GUIDELINES.md
+53 -4
View File
@@ -138,8 +138,42 @@ VERIFY → Compile successfully
- Verify line numbers match intended section
### Documentation
- ✅ Update **README.md** when users/admins need to be informed
- ✅ Document API changes with Bruno collections
**Documentation Structure** (updated with full docs system):
- ✅ **README.md** - Project overview, quick start, and setup instructions only
- ✅ **docs/** - Comprehensive documentation system with search
- ✅ **docs/api/** - API reference documentation (split by endpoint/category)
- ✅ **docs/devices/** - Device setup guides (KOBO, KOReader, etc.)
- ✅ **docs/contributing/** - Development and contribution guides
**Where to document changes**:
| Change Type | Location | Examples |
|-------------|----------|----------|
| **User-facing features** | `docs/` or appropriate subdirectory | New features, UI changes, workflows |
| **API endpoints** | `docs/api/<category>/<endpoint>.md` | New endpoints, modified responses, authentication changes |
| **API behavior** | Update existing `docs/api/` files | Parameter changes, error codes, rate limits |
| **Device setup** | `docs/devices/` | New device support, setup instructions |
| **Development** | `docs/contributing/` | Build changes, architecture decisions |
| **Quick start/setup** | `README.md` | Installation, environment setup, first-run |
| **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices |
| **Bug fixes** | Update relevant `docs/` only if user-visible | Clarifications, troubleshooting additions |
| **Bruno API tests** | `.bru` files alongside code | API contract testing, examples |
**Documentation Update Workflow**:
1. **Identify the audience** (end users, developers, API consumers)
2. **Choose appropriate location** based on table above
3. **Update documentation** before or with code changes
4. **Verify documentation renders** at `/docs` endpoint
5. **Test search** finds new/updated content
6. **For API changes**: Update both `docs/api/` files AND Bruno `.bru` files
7. **Commit separately** with clear message: `docs: <description>`
**When in doubt**:
- End-user visible → `docs/`
- API reference → `docs/api/`
- Setup/onboarding → `README.md`
- Development related → `docs/contributing/`
### Process & Continuity
- ✅ If mid-task and receive "no response", **continue the task**
@@ -216,7 +250,10 @@ git checkout -- internal/handlers/auth.go
- Impact analysis
- Alternative approaches considered
- [ ] Plan git commit structure (multiple logical commits)
- [ ] Identify if README.md needs updates
- [ ] **Identify documentation location** (see Documentation section):
- [ ] User-facing feature → `docs/`
- [ ] UI/workflow changes → `docs/`
- [ ] Setup instructions → `README.md`
### Before Making Full-Stack Changes
- [ ] Read current schema completely (if database changes)
@@ -224,6 +261,12 @@ git checkout -- internal/handlers/auth.go
- [ ] Plan exact changes needed
- [ ] Verify Podman will be used for builds
- [ ] Plan git commit structure (multiple logical commits)
- [ ] **Identify documentation location**:
- [ ] API changes → `docs/api/<category>/`
- [ ] New endpoints → Create new `.md` file in `docs/api/`
- [ ] API behavior → Update existing `docs/api/` files
- [ ] Breaking changes → Both `README.md` + relevant `docs/`
- [ ] Bruno `.bru` files → Update/create alongside API changes
### During Schema Changes (Full-Stack Only)
- [ ] Read current schema completely
@@ -247,7 +290,13 @@ git checkout -- internal/handlers/auth.go
- [ ] Run lint/typecheck if available
- [ ] Ensure no secrets in changes
- [ ] Verify logical commit structure
- [ ] Update README.md if user-facing changes
- [ ] **Update documentation** (see Documentation section):
- [ ] User-facing changes → `docs/`
- [ ] API changes → `docs/api/` + Bruno `.bru` files
- [ ] Setup/onboarding → `README.md`
- [ ] Development changes → `docs/contributing/`
- [ ] **Verify docs render** at `/docs` endpoint
- [ ] **Test docs search** finds new content
### Error Recovery Protocol (If Code Mistakes Occur)
- [ ] **Stop immediately** - don't make more edits