docs & ux improvmeents
This commit is contained in:
IGNY8 VPS (Salman)
229
RULES.md
Normal file
229
RULES.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# IGNY8 Documentation Rules
|
||||
|
||||
**Version:** 1.0
|
||||
**Last Updated:** December 25, 2025
|
||||
**Purpose:** Rules for maintaining consistent, accurate documentation
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Single Source of Truth** - One file per topic, no duplicates
|
||||
2. **Code is King** - Documentation reflects actual code, not plans
|
||||
3. **Tables Over Prose** - Use tables for lists of 3+ items
|
||||
4. **Code Paths Always** - Every feature links to exact files
|
||||
5. **Brief But Complete** - No fluff, every word has purpose
|
||||
|
||||
---
|
||||
|
||||
## File Structure Rules
|
||||
|
||||
### Root Folder (/)
|
||||
|
||||
Only these MD files allowed in root:
|
||||
- `CHANGELOG.md` - Version history
|
||||
- `RULES.md` - This file
|
||||
- `IGNY8-APP.md` - Executive summary (non-technical)
|
||||
- `README.md` - Project quickstart
|
||||
|
||||
**DO NOT CREATE** random MD files in root. All documentation goes in `/docs/`.
|
||||
|
||||
### Docs Folder (/docs/)
|
||||
|
||||
```
|
||||
docs/
|
||||
├── INDEX.md # Master navigation (update when adding docs)
|
||||
├── 00-SYSTEM/ # Architecture, auth, tenancy
|
||||
├── 10-MODULES/ # One file per module
|
||||
├── 20-API/ # API endpoints and schemas
|
||||
├── 30-FRONTEND/ # Pages, stores, components
|
||||
├── 40-WORKFLOWS/ # Cross-module flows
|
||||
└── 90-REFERENCE/ # Models, AI functions, troubleshooting
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Document Templates
|
||||
|
||||
### Module Document
|
||||
|
||||
Every module doc must include:
|
||||
|
||||
```markdown
|
||||
# [Module Name]
|
||||
|
||||
**Last Verified:** YYYY-MM-DD
|
||||
**Status:** ✅ Active | ⏸️ Inactive
|
||||
**Backend Path:** `backend/...`
|
||||
**Frontend Path:** `frontend/...`
|
||||
|
||||
## Quick Reference
|
||||
| What | File | Key Items |
|
||||
|------|------|-----------|
|
||||
|
||||
## Data Models
|
||||
[Tables with fields]
|
||||
|
||||
## API Endpoints
|
||||
| Method | Path | Handler | Purpose |
|
||||
|
||||
## Business Logic
|
||||
[Key operations with credit costs]
|
||||
|
||||
## Frontend Pages
|
||||
[Routes and components]
|
||||
|
||||
## Common Issues
|
||||
| Issue | Cause | Fix |
|
||||
|
||||
## Planned Changes
|
||||
| Feature | Status | Description |
|
||||
```
|
||||
|
||||
### Status Values
|
||||
|
||||
For Planned Changes tables:
|
||||
- ✅ Completed
|
||||
- 🐛 Bug (known issue)
|
||||
- 🔜 Planned (confirmed future work)
|
||||
- ⏸️ Pending (waiting on dependency)
|
||||
- ❌ Cancelled
|
||||
|
||||
---
|
||||
|
||||
## Update Rules
|
||||
|
||||
### When to Update Documentation
|
||||
|
||||
| Event | Action |
|
||||
|-------|--------|
|
||||
| New feature added | Update relevant module doc |
|
||||
| Bug fixed | Add to Common Issues if recurring |
|
||||
| API endpoint changed | Update API endpoints table |
|
||||
| Model changed | Update data models section |
|
||||
| Config changed | Update relevant doc |
|
||||
| Release | Update CHANGELOG.md |
|
||||
|
||||
### What to Update
|
||||
|
||||
| Change Type | Files to Update |
|
||||
|-------------|-----------------|
|
||||
| New module | Create module doc, update INDEX.md |
|
||||
| New endpoint | Module doc + API/ENDPOINTS.md |
|
||||
| New model | Module doc + 90-REFERENCE/MODELS.md |
|
||||
| Frontend page | Module doc + 30-FRONTEND/PAGES.md |
|
||||
| Bug fix | Common Issues in relevant doc |
|
||||
|
||||
### "Last Verified" Dates
|
||||
|
||||
Update `Last Verified:` date when:
|
||||
- You confirm the doc matches current code
|
||||
- After making changes to the doc
|
||||
- During documentation reviews
|
||||
|
||||
---
|
||||
|
||||
## Writing Style
|
||||
|
||||
### Do
|
||||
|
||||
- Use present tense ("Creates" not "Will create")
|
||||
- Use tables for any list of 3+ items
|
||||
- Include exact file paths
|
||||
- Link to related docs
|
||||
- Keep sentences short
|
||||
|
||||
### Don't
|
||||
|
||||
- Don't explain obvious things
|
||||
- Don't use jargon without defining
|
||||
- Don't duplicate info across files
|
||||
- Don't use passive voice
|
||||
- Don't leave TODOs in docs (use Planned Changes table)
|
||||
|
||||
### Code Path Format
|
||||
|
||||
```
|
||||
Backend: `backend/igny8_core/modules/planner/views.py:KeywordViewSet.bulk_delete`
|
||||
Frontend: `frontend/src/pages/Planner/Keywords.tsx:handleBulkDelete`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AI Agent Instructions
|
||||
|
||||
When AI agents (Copilot, Claude, etc.) make changes:
|
||||
|
||||
### After Code Changes
|
||||
|
||||
1. Identify which module(s) were modified
|
||||
2. Update the relevant module doc(s)
|
||||
3. If API changed, update API endpoints
|
||||
4. If model changed, update MODELS.md
|
||||
5. Update CHANGELOG.md for significant changes
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
- DO NOT create new MD files in root folder
|
||||
- DO NOT create "summary" or "implementation" docs
|
||||
- DO NOT duplicate existing documentation
|
||||
- DO NOT add verbose explanations
|
||||
- DO NOT leave placeholder content
|
||||
|
||||
### Verification Checklist
|
||||
|
||||
After documentation update:
|
||||
- [ ] File is in correct location (/docs/ structure)
|
||||
- [ ] INDEX.md updated if new file added
|
||||
- [ ] No duplicate information
|
||||
- [ ] All code paths are accurate
|
||||
- [ ] Tables used appropriately
|
||||
- [ ] Last Verified date updated
|
||||
|
||||
---
|
||||
|
||||
## Documentation Review Schedule
|
||||
|
||||
| Frequency | Action |
|
||||
|-----------|--------|
|
||||
| Per commit | Update affected docs |
|
||||
| Weekly | Review recent changes vs docs |
|
||||
| Monthly | Full audit: code vs docs |
|
||||
| Per release | Update CHANGELOG.md, verify all docs |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: File Locations
|
||||
|
||||
| Topic | File |
|
||||
|-------|------|
|
||||
| Master navigation | `docs/INDEX.md` |
|
||||
| Architecture | `docs/00-SYSTEM/ARCHITECTURE.md` |
|
||||
| Authentication | `docs/00-SYSTEM/AUTH-FLOWS.md` |
|
||||
| Multi-tenancy | `docs/00-SYSTEM/TENANCY.md` |
|
||||
| Planner module | `docs/10-MODULES/PLANNER.md` |
|
||||
| Writer module | `docs/10-MODULES/WRITER.md` |
|
||||
| Billing module | `docs/10-MODULES/BILLING.md` |
|
||||
| Automation | `docs/10-MODULES/AUTOMATION.md` |
|
||||
| Integrations | `docs/10-MODULES/INTEGRATIONS.md` |
|
||||
| Settings | `docs/10-MODULES/SYSTEM-SETTINGS.md` |
|
||||
| Linker (inactive) | `docs/10-MODULES/LINKER.md` |
|
||||
| Optimizer (inactive) | `docs/10-MODULES/OPTIMIZER.md` |
|
||||
| Publisher | `docs/10-MODULES/PUBLISHER.md` |
|
||||
| API endpoints | `docs/20-API/ENDPOINTS.md` |
|
||||
| All models | `docs/90-REFERENCE/MODELS.md` |
|
||||
| Troubleshooting | `docs/90-REFERENCE/TROUBLESHOOTING.md` |
|
||||
| Version history | `CHANGELOG.md` |
|
||||
| Executive summary | `IGNY8-APP.md` |
|
||||
|
||||
---
|
||||
|
||||
## Enforcement
|
||||
|
||||
These rules are enforced by:
|
||||
1. Code review checklist includes documentation
|
||||
2. AI agents instructed to follow these rules
|
||||
3. Monthly documentation audits
|
||||
4. CHANGELOG must be updated for releases
|
||||
|
||||
**When in doubt: Update the existing doc, don't create a new file.**
|
||||
Reference in New Issue
Block a user