# Documentation Continuous Improvement System - Setup Guide


**Last Updated:** 2025-11-20

## Initial Setup

### 1. Verify All Scripts Are Executable

```bash
chmod +x scripts/*.py scripts/*.sh
```

### 2. Create Required Directories

```bash
mkdir -p docs/metrics docs/debt docs/dashboard docs/reports docs/reviews docs/audits
```

### 3. Run Initial Health Check

```bash
python3 scripts/monitor-documentation-health.py --all
```

### 4. Generate Initial Reports

```bash
# Performance baseline
python3 scripts/measure-rule-performance.py --report

# Debt scan
python3 scripts/track-documentation-debt.py --scan --summary

# Weekly report
python3 scripts/generate-weekly-report.py
```

## Setting Up Automated Runs

### Cron Jobs (Linux/Mac)

Add to crontab (`crontab -e`):

```bash
# Daily health check at 9 AM
0 9 * * * cd /path/to/landingpage && python3 scripts/monitor-documentation-health.py --all > /dev/null 2>&1

# Weekly debt scan on Mondays at 10 AM
0 10 * * 1 cd /path/to/landingpage && python3 scripts/track-documentation-debt.py --scan > /dev/null 2>&1

# Weekly report on Mondays at 11 AM
0 11 * * 1 cd /path/to/landingpage && python3 scripts/generate-weekly-report.py > /dev/null 2>&1

# Monthly review on 1st of month at 9 AM
0 9 1 * * cd /path/to/landingpage && python3 scripts/monthly-documentation-review.py > /dev/null 2>&1
```

### GitHub Actions

The workflow (`.github/workflows/documentation-checks.yml`) is already configured and will run automatically on:

- Pull requests (when documentation files change)
- Pushes to master (when documentation files change)
- Weekly schedule (Mondays at 9 AM UTC)

## Email Alerts Configuration

To enable email alerts, update the alert scripts with SMTP configuration:

1. Edit `scripts/alert-documentation-health.py`
2. Uncomment and configure SMTP settings in the `send_alert()` method
3. Repeat for other alert scripts

Example SMTP configuration:

```python
server = smtplib.SMTP('smtp.example.com', 587)
server.starttls()
server.login('user', 'password')
```

## Pre-commit Hook Setup

The pre-commit hook is already installed at `.git/hooks/pre-commit`. It will automatically run when you commit changes to `.mdc` or `.md` files.

To test:

```bash
git add .cursor/rules/test.mdc
git commit -m "Test commit"
# Should run documentation checks automatically
```

## Dashboard Access

### Local Development

```bash
# Start a simple HTTP server
cd docs/dashboard
python3 -m http.server 8000

# Open in browser
open http://localhost:8000/index.html
```

### Production

The dashboards are static HTML files that can be served by any web server. They load data from:

- `docs/metrics/documentation-health.json`
- `docs/metrics/rule-performance-report.json`
- `docs/debt/backlog.json`

## Troubleshooting

### Scripts Not Found

Ensure you're in the project root directory:

```bash
cd /path/to/landingpage
```

### Permission Denied

Make scripts executable:

```bash
chmod +x scripts/*.py scripts/*.sh
```

### Import Errors

Ensure Python 3.6+ is installed:

```bash
python3 --version
```

### Missing Data Files

Run the monitoring scripts first to generate data files:

```bash
python3 scripts/monitor-documentation-health.py --all
python3 scripts/measure-rule-performance.py --report
python3 scripts/track-documentation-debt.py --scan
```

## Verification Checklist

- [x] All scripts are executable
- [x] Initial health check runs successfully
- [x] Dashboards load correctly
- [x] Pre-commit hook works
- [x] GitHub Actions workflow is configured
- [x] Scheduled workflow created (`.github/workflows/scheduled-documentation-checks.yml`)
- [x] Email alerts configured (SMTP placeholders added)
- [ ] Cron jobs are set up (if using local cron)
- [ ] Email alerts are enabled (set ENABLE_EMAIL_ALERTS=true and SMTP vars)

## Next Steps

1. Address current health issues (see `docs/metrics/documentation-health.json`)
2. Review debt backlog (see `docs/debt/backlog.json`)
3. Set up automated runs (cron or GitHub Actions)
4. Configure email alerts
5. Monitor dashboards regularly