Add markdown file analysis tools and reports
This commit is contained in:
defiQUG
256
docs/MARKDOWN_FILE_MAINTENANCE_GUIDE.md
Normal file
256
docs/MARKDOWN_FILE_MAINTENANCE_GUIDE.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user