# Contributing to Documentation

Guidelines for contributing to Ordio documentation.

**Last Updated:** 2026-02-28

## Developer Setup (Required for Rule Changes)

If you edit `.cursor/rules/`, the pre-push hook requires Python with PyYAML. Set up once:

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
```

See [DEV_TOOLING.md](development/DEV_TOOLING.md#python-setup-required-for-pre-push--rules) for details.

## Documentation Structure

Documentation is organized into the following sections:

- **`guides/`** - User-facing guides for creating pages and features
- **`systems/`** - Complete documentation for major systems (ShiftOps, Lead Capture, Product Updates)
- **`reference/`** - Technical reference (APIs, architecture, schemas)
- **`development/`** - Developer-focused docs (setup, testing, troubleshooting)
- **`ai/`** - AI agent-specific documentation
- **`archive/`** - Deprecated or outdated documentation

## Adding New Documentation

### 1. Choose the Right Location

- **User guides** → `guides/`
- **System documentation** → `systems/`
- **API/technical reference** → `reference/`
- **Developer docs** → `development/`
- **AI agent docs** → `ai/`

### 2. Follow Naming Conventions

- Use `UPPERCASE_WITH_UNDERSCORES.md` for main documents
- Use descriptive names that indicate content
- Avoid generic names like `README.md` except for index files

### 3. Update Index Files

When adding documentation, update the relevant `README.md` index file:

- `docs/README.md` - Main documentation index
- `docs/guides/README.md` - Guides index
- `docs/systems/README.md` - Systems index
- `docs/reference/README.md` - Reference index
- `docs/development/README.md` - Development index
- `docs/ai/README.md` - AI agent docs index

### 4. Add Cross-References

Link to related documentation:

```markdown
See [Related Guide](guides/comparison-pages/COMPARISON_PAGES_GUIDE.md) for more information.
```

**Note:** Always use the correct relative path from the current file's location.

### 5. Include Metadata

Add "Last Updated" date at the top or bottom:

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

**CRITICAL:** Always use accurate date:
- **For new files:** Use current date (check with `date +%Y-%m-%d`)
- **For existing files:** Use file modification date (check with `stat -f "%Sm" -t "%Y-%m-%d" filename`)
- **Never guess dates** or use placeholder dates

## Documentation Standards

### Formatting

- Use consistent heading levels (H1 for title, H2 for major sections)
- Use code blocks for code examples
- Use lists for step-by-step instructions
- Use tables for structured data

### Content Guidelines

- **Be clear and concise** - Get to the point quickly
- **Use active voice** - "Create the file" not "The file should be created"
- **Include examples** - Show, don't just tell
- **Cross-reference** - Link to related documentation
- **Keep it updated** - Update docs when code changes

### Code Examples

````markdown
```php
// Good: Clear, commented code
$competitorData = require __DIR__ . '/../data/competitors/competitor-slug.php';
```
````

```

### Links

- Use relative paths for internal links: `[Guide](guides/comparison-pages/COMPARISON_PAGES_GUIDE.md)`
- Use absolute paths from docs root: `docs/guides/comparison-pages/GUIDE.md`
- Verify links work before committing

## Updating Existing Documentation

### When to Update

- Code changes that affect documented behavior
- New features or systems
- Bug fixes that change workflows
- Outdated information

### How to Update

1. Find the relevant documentation file
2. Update the content
3. Update the "Last Updated" date
4. Verify cross-references still work
5. Update related index files if needed

## Cursor Rules vs Documentation

**Important:** Keep Cursor rules (`.cursor/rules/*.mdc`) separate from human documentation:

- **Cursor rules** - Concise AI agent instructions
- **Documentation** - Comprehensive human-readable guides

When updating Cursor rules, also update references in documentation if needed.

## Review Process

1. **Self-review** - Check formatting, links, and clarity
2. **Test links** - Verify all internal links work
3. **Check consistency** - Follow existing patterns
4. **Update indexes** - Add to relevant README files

## Questions?

- Check [README.md](README.md) for documentation structure
- See [QUICK_START.md](QUICK_START.md) for quick reference
- Review existing documentation for examples

```