# Documentation Maintenance Process

**Last Updated:** 2026-04-01

Complete workflow for maintaining and updating Ordio documentation.

## Maintenance Principles

### Before Creating New Documentation

1. **Search for existing documentation**

   - Check [DOCUMENTATION_INVENTORY.md](DOCUMENTATION_INVENTORY.md)
   - Search `docs/` directory
   - Check related directories (tools, pages, competitors, etc.)

2. **Check for redundant files**

   - Review [DOCUMENTATION_REDUNDANCY_REPORT.md](DOCUMENTATION_REDUNDANCY_REPORT.md)
   - Look for similar files that could be consolidated

3. **Identify gaps**
   - Review [DOCUMENTATION_GAPS.md](DOCUMENTATION_GAPS.md)
   - Check if documentation already exists for the topic

### Before Updating Documentation

1. **Check last updated date**

   - Verify when documentation was last updated
   - Determine if update is needed or if new file is required

2. **Review related documentation**

   - Check for cross-references that need updating
   - Verify links still work

3. **Follow update checklist**
   - Update "Last Updated" date
   - Update cross-references
   - Verify links
   - Update related inventory files

## Update Workflow

### Step 1: Identify What Needs Updating

- Code changes affecting documented behavior
- New features or systems
- Bug fixes changing workflows
- Outdated information
- Missing documentation

### Step 2: Find Existing Documentation

- Search [DOCUMENTATION_INVENTORY.md](DOCUMENTATION_INVENTORY.md)
- Use file naming patterns to locate docs
- Check related directories

### Step 3: Update or Create

**If documentation exists:**

- Update existing file
- Update "Last Updated" date
- Update cross-references
- Update related inventory files

**If documentation doesn't exist:**

- Create new file following [DOCUMENTATION_STANDARDS.md](DOCUMENTATION_STANDARDS.md)
- Add to relevant inventory files
- Create cross-references

### Step 4: Validate

- Run link validation: `python3 scripts/documentation/validate-links.py`
- Check dates: `python3 scripts/documentation/update-dates.py --check`
- Verify file naming conventions
- Test cross-references

## Redundancy Prevention

### Status File Management

**Rules:**

- One status file per system/directory maximum
- Update existing status files, don't create new ones
- Archive completed projects immediately
- Consolidate redundant status files quarterly

**Checklist Before Creating Status File:**

- [ ] Does a status file already exist in this directory?
- [ ] Can I update the existing file instead?
- [ ] Is this information unique or redundant?
- [ ] Should this be archived instead?

### Archive Process

**When to Archive:**

- Project completed → Delete completion reports (preserved in Git history)
- Implementation finished → Delete implementation reports (preserved in Git history)
- Historical status files → Delete if redundant with current status files (preserved in Git history)
- Outdated files → Delete (preserved in Git history)

**Current Approach:**

- **Prefer deletion over archiving** - Most historical files should be deleted
- All files preserved in Git history - can be retrieved with `git log` or `git show`
- Keep only active status files (FINAL_STATUS.md, NEXT_STEPS.md)
- Archive only if truly needed (rare cases)

**Archive Structure:**

- `docs/archive/completed-projects/` - Empty directory (reserved for future use if needed)
- `docs/archive/blog-migration/` - Blog migration documentation (README only)

**Note:** Historical files (old testing results, backups, implementation reports, completion summaries) have been deleted and are available in Git history. See `docs/archive/README.md` for Git access commands.

### Regular Cleanup Schedule

**Monthly:**

- Review new status files created
- Consolidate redundant files
- Archive completed projects

**Quarterly:**

- Comprehensive redundancy check
- Archive historical files
- Update documentation indexes
- Validate all links

**Annually:**

- Major documentation audit
- Archive old year directories
- Update master indexes
- Review and update standards
- **Cursor indexing review** – Review `.cursorignore` and `.cursorindexingignore`; run `python3 v2/scripts/dev-helpers/analyze-cursor-index.py`; consider new exclusions when adding large dirs (e.g., new blog category)

### Cursor Indexing Maintenance

- **After adding large directories** (e.g., new blog category): Run `python3 v2/scripts/dev-helpers/analyze-cursor-index.py`, consider adding patterns to `.cursorindexingignore`
- **Annual review:** See [CURSOR_INDEXING_SETUP.md](development/CURSOR_INDEXING_SETUP.md) and [CURSOR_INDEXING_OPTIMIZATION.md](development/CURSOR_INDEXING_OPTIMIZATION.md)

## Maintenance Schedule

### Monthly Tasks

- **Link validation** - Check all internal links
- **Date checks** - Verify dates are current
- **Redundancy scan** - Identify duplicate content
- **Gap analysis** - Identify missing documentation

**Commands:**

```bash
python3 scripts/documentation/validate-links.py
python3 scripts/documentation/inventory-documentation.py
python3 scripts/documentation/check-redundancy.py
python3 scripts/documentation/update-dates.py --check
```

### Quarterly Tasks

- **Comprehensive review** - Review all documentation
- **Consolidation** - Merge redundant files
- **Cross-reference update** - Update all cross-references
- **Structure review** - Verify directory structure

**Commands:**

```bash
python3 scripts/documentation/inventory-documentation.py
python3 scripts/documentation/consolidate-docs.py --dry-run
```

### Annual Tasks

- **Major structure review** - Review entire documentation structure
- **Archive old docs** - Move outdated docs to archive
- **Update all dates** - Ensure all dates are current year
- **Review for new AI models** - Optimize for latest AI capabilities

**Commands:**

```bash
python3 scripts/documentation/annual-documentation-audit.py
python3 v2/scripts/dev-helpers/analyze-cursor-index.py --output docs/development/cursor-index-baseline.json
```

## Update Checklist

### When Updating Existing Documentation

- [ ] Read existing documentation completely
- [ ] Identify what needs updating
- [ ] Update content
- [ ] Update "Last Updated" date (use accurate date)
- [ ] Update cross-references
- [ ] Verify internal links
- [ ] Update related inventory files
- [ ] Run validation scripts
- [ ] Test links and cross-references

### When Creating New Documentation

- [ ] Search for existing documentation first
- [ ] Check [DOCUMENTATION_GAPS.md](DOCUMENTATION_GAPS.md)
- [ ] Follow [DOCUMENTATION_STANDARDS.md](DOCUMENTATION_STANDARDS.md)
- [ ] Use appropriate file naming convention
- [ ] Add "Last Updated" date (current date)
- [ ] Add cross-references to related docs
- [ ] Add to relevant inventory files
- [ ] Update master index if needed
- [ ] Run validation scripts

## Automation Scripts

### Documentation inventory (single source of truth)

Two scripts used to overwrite [DOCUMENTATION_INVENTORY.md](DOCUMENTATION_INVENTORY.md) with different behavior: the legacy root script skipped `docs/archive` and did not emit JSON; [scripts/documentation/inventory-documentation.py](../scripts/documentation/inventory-documentation.py) walks the full `docs/` tree (including archive), writes a **slim** markdown summary by default (full path list in [documentation-inventory.json](documentation-inventory.json)), and produces the JSON that [check-redundancy.py](../scripts/documentation/check-redundancy.py) requires. **Use the `scripts/documentation/` pipeline only.** Durable notes that must not be lost on regen live in [DOCUMENTATION_INVENTORY_MANUAL_NOTES.md](DOCUMENTATION_INVENTORY_MANUAL_NOTES.md). [scripts/generate-documentation-inventory.py](../scripts/generate-documentation-inventory.py) is a deprecated wrapper that delegates to the canonical script.

### Available Scripts

See also **[scripts/documentation/README.md](../scripts/documentation/README.md)** (Tier A vs Tier B scripts).

Located in `scripts/documentation/`:

1. **inventory-documentation.py** - Generate inventory reports + `documentation-inventory.json`
2. **check-redundancy.py** - Identify duplicate content
3. **validate-links.py** - Check broken links
4. **update-dates.py** - Ensure dates are current
5. **find-documentation.py** - Search tool for finding docs
6. **consolidate-docs.py** - Merge redundant files

### Running Scripts

```bash
# Generate inventory (always run before redundancy; JSON is required)
python3 scripts/documentation/inventory-documentation.py

# Check redundancy (reads docs/documentation-inventory.json)
python3 scripts/documentation/check-redundancy.py

# Validate links
python3 scripts/documentation/validate-links.py

# Update dates (check only)
python3 scripts/documentation/update-dates.py --check

# Find documentation
python3 scripts/documentation/find-documentation.py "search term"
```

## Documentation Lifecycle

### Creation

1. Identify need for documentation
2. Search for existing documentation
3. Create following standards
4. Add to inventory
5. Create cross-references

### Maintenance

1. Regular updates as code changes
2. Monthly validation checks
3. Quarterly comprehensive review
4. Annual major review

### Archival

1. Identify outdated documentation
2. Delete redundant files (preserve in Git history)
3. Update cross-references
4. Update inventory

## AI Agent Optimization Review Steps

### When Updating Documentation

1. **Check AI discoverability**

   - Verify headings are descriptive and searchable
   - Check keywords are included
   - Verify cross-references are present
   - Check semantic search patterns are followed

2. **Validate cross-references**

   - Verify "Related Documentation" section present
   - Check "Related Cursor Rules" section present (if applicable)
   - Verify bidirectional links work
   - Check rule-to-doc mapping is updated

3. **Update rule-to-doc mapping**
   - If new documentation created, update `docs/ai/RULE_TO_DOC_MAPPING.md`
   - If new rules created, update mapping
   - Regenerate JSON mapping: `python3 scripts/documentation/generate-rule-doc-mapping.py`

### When Updating Rules

1. **Check metadata completeness**

   - Verify description, globs, alwaysApply fields present
   - Check "Related Documentation" section present
   - Verify glob patterns are correct

2. **Update cross-references**

   - Update "Related Documentation" section if docs change
   - Check documentation's "Related Cursor Rules" sections
   - Verify bidirectional links work

3. **Regenerate metadata index**
   - Run: `python3 scripts/documentation/generate-rule-metadata-index.py`
   - Verify METADATA_INDEX.json is updated

### Cross-Reference Validation Steps

1. **Run validation script**

   - `python3 scripts/documentation/validate-cross-references.py` (when created)
   - Fix broken cross-references
   - Verify bidirectional links work

2. **Manual checks**

   - Check rule files have "Related Documentation" sections
   - Check documentation files have "Related Cursor Rules" sections
   - Verify links work in both directions

3. **Update mapping files**
   - Update `docs/ai/RULE_TO_DOC_MAPPING.md` if needed
   - Regenerate JSON mapping if structure changes

### Rule-to-Doc Mapping Updates

**When documentation changes:**

- Update `docs/ai/RULE_TO_DOC_MAPPING.md` if new docs created
- Regenerate JSON: `python3 scripts/documentation/generate-rule-doc-mapping.py`

**When rules change:**

- Update rule's "Related Documentation" section
- Update `docs/ai/RULE_TO_DOC_MAPPING.md` if mapping changes
- Regenerate JSON: `python3 scripts/documentation/generate-rule-doc-mapping.py`

## Related Documentation

- **[Documentation Standards](DOCUMENTATION_STANDARDS.md)** - File naming and structure
- **[Documentation Inventory](DOCUMENTATION_INVENTORY.md)** - Complete file inventory
- **[Documentation Gaps](DOCUMENTATION_GAPS.md)** - Missing documentation
- **[Redundancy Report](DOCUMENTATION_REDUNDANCY_REPORT.md)** - Redundant files
- **[AI Agent Guide](AI_AGENT_GUIDE.md)** - Complete documentation discovery guide
- **[Documentation Quality Checklist](DOCUMENTATION_QUALITY_CHECKLIST.md)** - Quality checklist for AI agents
- **[Semantic Search Index](ai/SEMANTIC_SEARCH_INDEX.md)** - Query → documentation mapping
- **[Rule Discovery Patterns](ai/RULE_DISCOVERY_PATTERNS.md)** - File path → rule mapping