257 lines
6.4 KiB
Markdown
257 lines
6.4 KiB
Markdown
# Markdown File Maintenance Guide
|
|
|
|
**Last Updated**: 2026-01-05
|
|
**Purpose**: Guidelines for maintaining clean, organized markdown files
|
|
|
|
---
|
|
|
|
## File Organization Standards
|
|
|
|
### Root Directory (`/`)
|
|
**Should contain ONLY**:
|
|
- `README.md` - Main project README
|
|
- `PROJECT_STRUCTURE.md` - Project structure documentation
|
|
|
|
**Should NOT contain**:
|
|
- Status reports
|
|
- Completion reports
|
|
- Analysis reports
|
|
- Timestamped snapshots
|
|
- Temporary fix guides
|
|
|
|
### Documentation Directory (`docs/`)
|
|
**Should contain**:
|
|
- Permanent documentation
|
|
- Architecture guides
|
|
- Configuration guides
|
|
- Tutorials and how-tos
|
|
- API documentation
|
|
|
|
**Should NOT contain**:
|
|
- Status/completion reports (→ `reports/`)
|
|
- Temporary fix guides (→ `docs/09-troubleshooting/archive/`)
|
|
- Timestamped snapshots (→ `reports/archive/`)
|
|
|
|
### Reports Directory (`reports/`)
|
|
**Should contain**:
|
|
- All status reports
|
|
- All analysis reports
|
|
- All diagnostic reports
|
|
- Timestamped snapshots (in `archive/` subdirectories)
|
|
|
|
**Structure**:
|
|
```
|
|
reports/
|
|
├── status/ # Current status reports
|
|
├── analyses/ # Analysis reports
|
|
├── inventories/ # Inventory reports
|
|
└── archive/ # Archived reports by date
|
|
└── YYYY-MM-DD/ # Date-specific archives
|
|
```
|
|
|
|
### Submodule Directories
|
|
**Each submodule should have**:
|
|
- `README.md` - Submodule documentation
|
|
- `docs/` - Submodule-specific documentation
|
|
- `reports/` or `archive/` - Status/completion files
|
|
|
|
---
|
|
|
|
## File Naming Conventions
|
|
|
|
### Documentation Files
|
|
- Use `UPPERCASE_WITH_UNDERSCORES.md`
|
|
- Be descriptive: `NETWORK_ARCHITECTURE.md` not `network.md`
|
|
- Use consistent prefixes:
|
|
- `README.md` - Directory overview
|
|
- `QUICK_START.md` - Quick start guide
|
|
- `DEPLOYMENT.md` - Deployment guide
|
|
- `TROUBLESHOOTING.md` - Troubleshooting guide
|
|
|
|
### Status/Report Files
|
|
- Use descriptive names: `SERVICE_STATUS.md` not `status.md`
|
|
- Avoid timestamps in filenames (use archive directories instead)
|
|
- Use consistent suffixes:
|
|
- `*_STATUS.md` - Current status
|
|
- `*_REPORT.md` - Analysis report
|
|
- `*_SUMMARY.md` - Summary report
|
|
|
|
### Temporary Files
|
|
- Prefix with `TEMP_` or `ARCHIVE_`
|
|
- Move to archive directories promptly
|
|
- Delete after 90 days if no longer needed
|
|
|
|
---
|
|
|
|
## When to Create Files
|
|
|
|
### ✅ Create Documentation When:
|
|
- Documenting a new feature or component
|
|
- Creating a guide or tutorial
|
|
- Documenting architecture or design decisions
|
|
- Creating API documentation
|
|
|
|
### ✅ Create Reports When:
|
|
- Generating status reports
|
|
- Creating analysis reports
|
|
- Documenting diagnostic findings
|
|
- Creating inventory snapshots
|
|
|
|
### ❌ Don't Create Files For:
|
|
- Temporary notes (use issue tracker or notes app)
|
|
- One-time commands (use scripts)
|
|
- Duplicate status (update existing file)
|
|
- Placeholder content (wait until content is ready)
|
|
|
|
---
|
|
|
|
## When to Archive Files
|
|
|
|
### Archive When:
|
|
- File is older than 90 days AND superseded by newer version
|
|
- File is a timestamped snapshot
|
|
- File documents a completed task (not ongoing)
|
|
- File is a temporary fix guide (issue resolved)
|
|
|
|
### Archive Location:
|
|
- `reports/archive/YYYY-MM-DD/` - For dated reports
|
|
- `docs/09-troubleshooting/archive/` - For resolved troubleshooting guides
|
|
- `{submodule}/docs/archive/` - For submodule-specific archives
|
|
|
|
### Archive Naming:
|
|
- Keep original filename
|
|
- Add date prefix if needed: `YYYY-MM-DD_original-name.md`
|
|
- Create `README.md` in archive directory explaining contents
|
|
|
|
---
|
|
|
|
## When to Delete Files
|
|
|
|
### Safe to Delete:
|
|
- Duplicate files (keep most recent)
|
|
- Empty or placeholder files
|
|
- Files marked as deprecated
|
|
- Old temporary files (>90 days, archived)
|
|
|
|
### Never Delete:
|
|
- `README.md` files
|
|
- Active documentation
|
|
- Files referenced by other files
|
|
- Files in git history (use git to remove)
|
|
|
|
---
|
|
|
|
## Maintenance Checklist
|
|
|
|
### Weekly
|
|
- [ ] Review root directory for misplaced files
|
|
- [ ] Archive timestamped snapshots older than 7 days
|
|
- [ ] Check for duplicate status files
|
|
|
|
### Monthly
|
|
- [ ] Review `reports/` organization
|
|
- [ ] Archive completed status reports
|
|
- [ ] Update cross-references
|
|
- [ ] Check for broken links
|
|
|
|
### Quarterly
|
|
- [ ] Review archive directories
|
|
- [ ] Delete old temporary files (>90 days)
|
|
- [ ] Consolidate duplicate documentation
|
|
- [ ] Update file organization standards
|
|
|
|
---
|
|
|
|
## Automated Maintenance
|
|
|
|
### Analysis Scripts
|
|
```bash
|
|
# Analyze all markdown files
|
|
python3 scripts/analyze-markdown-files.py
|
|
|
|
# Check for inconsistencies
|
|
python3 scripts/check-content-inconsistencies.py
|
|
|
|
# Cleanup files
|
|
bash scripts/cleanup-markdown-files.sh
|
|
```
|
|
|
|
### Git Hooks (Optional)
|
|
Create `.git/hooks/pre-commit` to check for:
|
|
- Files in wrong directories
|
|
- Broken cross-references
|
|
- Placeholder content
|
|
|
|
---
|
|
|
|
## Common Issues and Solutions
|
|
|
|
### Issue: Too many files in root
|
|
**Solution**: Move status/report files to `reports/`
|
|
|
|
### Issue: Duplicate status files
|
|
**Solution**: Consolidate to single status file per component
|
|
|
|
### Issue: Broken cross-references
|
|
**Solution**: Update links or move files to correct location
|
|
|
|
### Issue: Outdated content
|
|
**Solution**: Archive or update with current information
|
|
|
|
### Issue: Temporary files accumulating
|
|
**Solution**: Archive or delete after 90 days
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
1. **One Source of Truth**: Don't duplicate status information
|
|
2. **Clear Organization**: Follow directory structure standards
|
|
3. **Descriptive Names**: Use clear, consistent file names
|
|
4. **Regular Cleanup**: Archive or delete old files regularly
|
|
5. **Cross-Reference**: Keep links between related files updated
|
|
6. **Document Decisions**: Explain why files are organized as they are
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### File Locations
|
|
| Type | Location |
|
|
|------|----------|
|
|
| Main README | `/README.md` |
|
|
| Project Structure | `/PROJECT_STRUCTURE.md` |
|
|
| Documentation | `/docs/` |
|
|
| Status Reports | `/reports/status/` |
|
|
| Analysis Reports | `/reports/analyses/` |
|
|
| Archived Reports | `/reports/archive/YYYY-MM-DD/` |
|
|
| Temporary Fixes | `/docs/09-troubleshooting/archive/` |
|
|
|
|
### Commands
|
|
```bash
|
|
# Count markdown files
|
|
find . -name "*.md" -type f | wc -l
|
|
|
|
# Find files in root
|
|
find . -maxdepth 1 -name "*.md" -type f
|
|
|
|
# Find duplicate names
|
|
find . -name "*.md" -type f | xargs basename | sort | uniq -d
|
|
|
|
# Check for broken links (requires markdown-link-check)
|
|
find . -name "*.md" -type f -exec markdown-link-check {} \;
|
|
```
|
|
|
|
---
|
|
|
|
## Questions?
|
|
|
|
- Review `MARKDOWN_FILES_COMPREHENSIVE_REPORT.md` for detailed analysis
|
|
- Check `CONTENT_INCONSISTENCIES.json` for specific issues
|
|
- Run analysis scripts for current status
|
|
|
|
---
|
|
|
|
**Maintained By**: Project Team
|
|
**Last Review**: 2026-01-05
|