9cef9b8d57
Merge _configs/ into config/ for single configuration directory. Update all path references. Changes: - Move _configs/* to config/ - Update .gitignore for new patterns - No code references to _configs/ found Impact: -1 root directory (layout_conventions.md compliance)
327 lines
8.2 KiB
Markdown
327 lines
8.2 KiB
Markdown
# Documentation Review Rules
|
|
|
|
Standards for cleaning and maintaining documentation across all projects.
|
|
|
|
---
|
|
|
|
## 🎯 Core Rules
|
|
|
|
### 1. ❌ Remove Absolute User Paths
|
|
**Rule**: No hardcoded user home or development paths in documentation.
|
|
|
|
**Pattern to Remove**:
|
|
- `/Users/Akasha/Development/<project>`
|
|
- `/Users/Akasha/Tools/...`
|
|
- `/Users/Akasha/.coder/...`
|
|
- Any machine-specific absolute paths
|
|
|
|
**Replacement**:
|
|
- Use relative paths: `cd vapora`, `./scripts/`, `crates/`
|
|
- Use home directory notation: `~/.config/`, `~/projects/`
|
|
- Use placeholders: `<your-dev-directory>`, `<project-root>`
|
|
|
|
**Example**:
|
|
```bash
|
|
# ❌ BAD
|
|
cd /Users/Akasha/Development/syntaxis
|
|
cargo build
|
|
|
|
# ✅ GOOD
|
|
# Navigate to project root
|
|
cargo build
|
|
```
|
|
|
|
---
|
|
|
|
### 2. ❌ No References to .claude or claude Directories
|
|
**Rule**: Do NOT mention `.claude/`, `.claude/info/`, or related directories in user-facing documentation.
|
|
|
|
**Pattern to Remove**:
|
|
- `.claude/CLAUDE.md` or `CLAUDE.md` references in README
|
|
- `.claude/info/PHASE_X_COMPLETION.md` links
|
|
- `.claude/summaries/fase-X.md` references
|
|
- `.coder/` directory mentions (internal project tracking)
|
|
- "See CLAUDE.md for..." instructions
|
|
- References to internal Claude Code configuration
|
|
|
|
**Replacement**:
|
|
- Remove entirely from user-facing docs
|
|
- Keep only in internal/development documentation
|
|
- Link to public-facing docs: README.md, docs/ARCHITECTURE.md, etc.
|
|
|
|
**Example**:
|
|
```markdown
|
|
# ❌ BAD
|
|
See `CLAUDE.md` for complete project overview
|
|
See `.claude/info/PHASE_9_COMPLETION.md` for details
|
|
See `.coder/summaries/fase-1-backend.md` for implementation
|
|
|
|
# ✅ GOOD
|
|
See `README.md` for project overview
|
|
See `docs/ARCHITECTURE.md` for system design
|
|
See `docs/QUICKSTART.md` for getting started
|
|
```
|
|
|
|
---
|
|
|
|
### 3. ❌ Remove Phase/Release References
|
|
**Rule**: No references to development phases, completion status, or internal timelines.
|
|
|
|
**Pattern to Remove**:
|
|
- "Phase 1-12", "Phase 8-9", "Phases 1-7"
|
|
- "Week 1-4", "Week 5-8", etc.
|
|
- Phase completion badges
|
|
- Phase-specific documentation links
|
|
|
|
**Replacement**:
|
|
- Describe functionality directly: "Advanced Features", "Core Capabilities"
|
|
- Remove phase-specific docs from user-facing tables
|
|
- Use feature-based organization
|
|
|
|
**Example**:
|
|
```markdown
|
|
# ❌ BAD
|
|
## Phase 9: Advanced Resilience & Observability ✅
|
|
- Phase 9a: Real async SSH integration (8 tests)
|
|
- Phase 9b: Connection pooling (10 tests)
|
|
|
|
# ✅ GOOD
|
|
## Advanced Features
|
|
- Real async SSH integration
|
|
- Automatic connection pooling
|
|
```
|
|
|
|
---
|
|
|
|
### 4. ❌ Remove Test Coverage Metrics
|
|
**Rule**: Don't advertise specific test counts or coverage percentages in user-facing docs.
|
|
|
|
**Pattern to Remove**:
|
|
- "691+ tests passing"
|
|
- "332+ tests (100% pass rate)"
|
|
- "64 tests", "155/155 passing"
|
|
- Coverage percentages in badges
|
|
- Test count tables
|
|
|
|
**Replacement**:
|
|
- Use generic language: "Comprehensive tests", "Fully tested", "Complete test coverage"
|
|
- Keep detailed test info only in internal documentation
|
|
|
|
**Example**:
|
|
```markdown
|
|
# ❌ BAD
|
|
[]
|
|
|
|
**Test Coverage**:
|
|
- TUI Tests: 52 passing ✅
|
|
- Dashboard Tests: 12 passing ✅
|
|
- Total: 64 tests
|
|
|
|
# ✅ GOOD
|
|
✅ **Comprehensive tests** — All critical paths tested
|
|
✅ **100% documented** — All public APIs documented with rustdoc
|
|
```
|
|
|
|
---
|
|
|
|
### 5. ❌ Remove Phase-Specific Documentation Links
|
|
**Rule**: Don't link to phase completion documents or internal tracking in README/docs.
|
|
|
|
**Pattern to Remove**:
|
|
- `.coder/info/PHASE_9_COMPLETION.md`
|
|
- `.coder/info/README_PHASE_8.md`
|
|
- `.coder/summaries/fase-1-backend.md`
|
|
- `.coder/init/PHASE_1_COMPLETE.md`
|
|
|
|
**Keep**:
|
|
- Main documentation: README.md, docs/ARCHITECTURE.md, docs/QUICKSTART.md
|
|
- User-facing guides only
|
|
|
|
**Example**:
|
|
```markdown
|
|
# ❌ BAD
|
|
| Phase 8 Features | [.coder/info/README_PHASE_8.md](.coder/info/README_PHASE_8.md) |
|
|
| Phase 9 Details | [.coder/info/PHASE_9_COMPLETION.md](.coder/info/PHASE_9_COMPLETION.md) |
|
|
|
|
# ✅ GOOD
|
|
| Project Overview | [README.md](README.md) |
|
|
| System Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
|
|
| Installation Guide | [docs/docs/installation-guide.md](docs/docs/installation-guide.md) |
|
|
```
|
|
|
|
---
|
|
|
|
### 6. ❌ Remove Internal Tool Paths
|
|
**Rule**: Don't reference external tool paths in documentation.
|
|
|
|
**Pattern to Remove**:
|
|
- `/Users/Akasha/Tools/doc-lifecycle-manager`
|
|
- `/Users/Akasha/Tools/tracking-manager`
|
|
- `/Users/Akasha/Tools/dev-system`
|
|
|
|
**Replacement**:
|
|
- Generic reference: "External project", "Related project"
|
|
- Link to public repo if available
|
|
|
|
**Example**:
|
|
```toml
|
|
# ❌ BAD
|
|
**Project Location**: `/Users/Akasha/Tools/doc-lifecycle-manager`
|
|
|
|
# ✅ GOOD
|
|
**Project Location**: External project (doc-lifecycle-manager)
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Files to Review
|
|
|
|
### Always Check These:
|
|
- ✅ `README.md` (root)
|
|
- ✅ `QUICKSTART.md`
|
|
- ✅ `docs/*.md`
|
|
- ✅ Root-level guide files (SETUP.md, DEPLOYMENT.md, etc.)
|
|
|
|
### Exclude From Review:
|
|
- ❌ `.claude/` directory (internal Claude Code instructions)
|
|
- ❌ `.coder/` directory (internal project tracking)
|
|
- ❌ `CLAUDE.md` (internal instructions for Claude Code)
|
|
- ❌ `DEPENDENCIES.md` (dependency listing)
|
|
- ❌ `guides/archive/` (historical reference)
|
|
|
|
---
|
|
|
|
## 🔍 Review Checklist
|
|
|
|
When reviewing documentation, check for:
|
|
|
|
### Path Check
|
|
- [ ] No `/Users/Akasha/Development/...` paths
|
|
- [ ] No `/Users/Akasha/Tools/...` paths
|
|
- [ ] Uses relative paths: `cd vapora`, `./scripts/`
|
|
- [ ] Uses home notation: `~/.config/`, `~/projects/`
|
|
|
|
### Claude/Internal Check
|
|
- [ ] No `.claude/` directory references
|
|
- [ ] No `CLAUDE.md` references
|
|
- [ ] No `.coder/` directory references
|
|
- [ ] No "See CLAUDE.md" or similar instructions
|
|
- [ ] No Claude Code internal configuration mentioned
|
|
|
|
### Phase Check
|
|
- [ ] No "Phase X" references in user-facing docs
|
|
- [ ] No "Week X-Y" timelines
|
|
- [ ] No phase completion badges
|
|
- [ ] No phase-specific documentation tables
|
|
|
|
### Test Coverage Check
|
|
- [ ] No specific test count numbers ("332+ tests")
|
|
- [ ] No test pass rate percentages ("100% passing")
|
|
- [ ] Uses generic: "Comprehensive tests", "Fully tested"
|
|
- [ ] Test metrics only in internal documentation
|
|
|
|
### Documentation Link Check
|
|
- [ ] No `.coder/` links in README/docs
|
|
- [ ] No `.claude/` links anywhere in user docs
|
|
- [ ] No internal phase completion files linked
|
|
- [ ] Only user-facing documentation listed
|
|
- [ ] Links are to main docs: README, QUICKSTART, ARCHITECTURE
|
|
|
|
### Internal Tool Check
|
|
- [ ] No specific tool paths referenced
|
|
- [ ] External dependencies referenced generically
|
|
- [ ] Public repo links where available
|
|
|
|
---
|
|
|
|
## 📝 Examples by Project
|
|
|
|
### ✅ Correct Pattern - README.md
|
|
|
|
```markdown
|
|
# Project Name
|
|
|
|
[](LICENSE)
|
|
[]
|
|
[]
|
|
|
|
**Description** of what the project does without mentioning phases or test counts.
|
|
|
|
## Features
|
|
|
|
✅ **Feature Group 1**
|
|
- Feature detail
|
|
- Feature detail
|
|
|
|
✅ **Feature Group 2**
|
|
- Feature detail
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Build the project
|
|
cargo build --release
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Quick Start](QUICKSTART.md)
|
|
- [Architecture](docs/ARCHITECTURE.md)
|
|
- [CLI Guide](docs/CLI_GUIDE.md)
|
|
```
|
|
|
|
### ✅ Correct Pattern - Code Blocks in Docs
|
|
|
|
```bash
|
|
# ✅ GOOD - Relative paths
|
|
cd project-name
|
|
cargo build --release
|
|
|
|
# ✅ GOOD - Home directory
|
|
cp configs/database-default.toml ~/.config/project/database.toml
|
|
|
|
# ✅ GOOD - Relative from root
|
|
cd crates/subproject
|
|
cargo test
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 How to Use These Rules
|
|
|
|
### For Interactive Review:
|
|
```bash
|
|
# Check a markdown file against these rules
|
|
claude-code review-docs <file.md> --rules DOC_REVIEW_RULES.md
|
|
```
|
|
|
|
### For Batch Review:
|
|
```bash
|
|
# Review all markdown in a directory
|
|
claude-code review-docs docs/ --rules DOC_REVIEW_RULES.md --recursive
|
|
```
|
|
|
|
### In CI/CD:
|
|
```yaml
|
|
# Example: pre-commit hook
|
|
- name: Review Documentation
|
|
run: |
|
|
claude-code review-docs README.md docs/ \
|
|
--rules .claude/DOC_REVIEW_RULES.md \
|
|
--fail-on-violations
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Related Documentation
|
|
|
|
- See individual project README for specific conventions
|
|
- See `docs/ARCHITECTURE.md` for technical details
|
|
- See `docs/QUICKSTART.md` for getting started
|
|
|
|
---
|
|
|
|
**Version**: 1.0
|
|
**Last Updated**: 2025-11-19
|
|
**Status**: Active - Use for all documentation reviews
|