# Documentation Standards

**Last Updated:** 2026-01-20

Standards and conventions for all Ordio documentation files.

**Note:** Documentation structure was restructured on 2026-01-10. See [RESTRUCTURING_COMPLETE.md](RESTRUCTURING_COMPLETE.md) for details.

## Status File Management

### Status File Consolidation Rules

**Principle:** One status file per system/directory

**Allowed Status Files:**

- `PROJECT_STATUS.md` or `FINAL_STATUS.md` - Current project status (one per directory)
- `NEXT_STEPS.md` - Future actions and next steps (one per directory)
- `IMPLEMENTATION_SUMMARY.md` - Active implementation status (one per active project)

**Prohibited Patterns:**

- Multiple FINAL_STATUS files in same directory
- Multiple NEXT_STEPS files in same directory
- Status files with dates in filename (e.g., `FINAL_STATUS_2026.md`) unless year-specific
- Redundant status files (e.g., `FINAL_STATUS_AND_NEXT_STEPS.md`)

**Consolidation Process:**

1. Review all status files in directory
2. Identify unique content
3. Consolidate into single authoritative file
4. Archive historical versions
5. Update all references
6. Delete redundant files

**Archive Criteria:**

- Completed projects → Delete redundant completion reports (preserve in Git history)
- Historical status files → Delete if redundant with current status files
- Completed implementations → Delete redundant implementation reports

**Note:** Archive directory was deleted as all archived files were redundant completion/status reports. Historical information is preserved in Git history.

## File Naming Conventions

### Documentation Files

- **Main documents:** `UPPERCASE_WITH_UNDERSCORES.md`
- **Tool documentation:** `[tool-slug]-documentation.md`
- **Competitor profiles:** `[competitor-slug]-profile.md`
- **Page documentation:** `[page-slug]-documentation.md`
- **Feature documentation:** `[feature-slug]-documentation.md`
- **Index files:** `README.md` or `[SECTION]_INVENTORY.md`

### Examples

- ✅ `TOOLS_INVENTORY.md`
- ✅ `minijob-rechner-documentation.md`
- ✅ `personio-profile.md`
- ✅ `schichtplanung-documentation.md`
- ❌ `tools inventory.md` (spaces)
- ❌ `MinijobRechner.md` (wrong format)

## File Structure Template

### Standard Documentation File

```markdown
# Document Title

**Last Updated:** YYYY-MM-DD

Brief description of document purpose.

## Section 1

Content here...

## Section 2

Content here...

## Related Documentation

- [Documentation Maintenance Process](DOCUMENTATION_MAINTENANCE_PROCESS.md) - Update workflows
- [Documentation Inventory](DOCUMENTATION_INVENTORY.md) - Complete file inventory
```

### Tool Documentation Template

```markdown
# [Tool Name] Documentation

**Last Updated:** YYYY-MM-DD

## Purpose and Use Cases

What the tool does and when to use it.

## Technical Implementation

### Files

- PHP: `v2/pages/tools_[tool-slug].php`
- JavaScript: `v2/js/tools-[tool-slug]-calculator.js`

### Calculation Logic

How calculations work...

## Content Structure

### Hero Section

- H1 title
- Meta description
- Trust badges

### FAQs

- FAQ count
- Common questions

## Maintenance Requirements

- Year update checklist
- Legal compliance requirements
- Data source updates
```

## Date Management

### CRITICAL: Always Use Accurate Dates

**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 use placeholder dates (2026-01-20, 2026-01-20, etc.)
- Never guess dates

**Format:**

- Standard: `**Last Updated:** YYYY-MM-DD`
- Place immediately after H1 title

See [DATE_MANAGEMENT_GUIDELINES.md](DATE_MANAGEMENT_GUIDELINES.md) for complete standards.

## Link Formatting

### Internal Links

- Use relative paths from docs root: `[Link Text](guides/PAGE_TYPE_GUIDES.md)` or relative from current file: `[Link Text](guides/PAGE_TYPE_GUIDES.md)`
- Use absolute paths from docs root: `docs/guides/PAGE_TYPE_GUIDES.md`
- Always verify links work before committing

**Examples:**

- `[Page Type Guides](guides/PAGE_TYPE_GUIDES.md)` - Relative path from docs root
- `docs/guides/PAGE_TYPE_GUIDES.md` - Absolute path from project root

### External Links

- Use full URLs: `https://www.ordio.com/path`
- Mark external links clearly if needed

## Cross-Reference Patterns

### Linking to Related Documentation

```markdown
## Related Documentation

- **[Page Type Guides](guides/PAGE_TYPE_GUIDES.md)** - Quick reference for all page types
- **[ShiftOps Documentation](systems/shiftops/README.md)** - ShiftOps system documentation
- **[Comparison Pages Guide](guides/comparison-pages/COMPARISON_PAGES_GUIDE.md)** - Comparison page creation guide
- **[Cursor Rules](.cursor/rules/comparison-pages-core.mdc)** - Cursor AI rules for comparison pages
```

**Note:** Replace placeholder paths with actual documentation paths. See [docs/ai/RULE_TO_DOC_MAPPING.md](ai/RULE_TO_DOC_MAPPING.md) for rule-to-documentation mappings.

## Content Guidelines

### Writing Style

- **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
$data = require __DIR__ . '/../data/file.php';
```
````

```

### Lists and Tables

- Use consistent formatting
- Use tables for structured data
- Use lists for step-by-step instructions

## Directory Structure Standards

### Content Documentation

```

docs/content/
├── tools/ # REMOVED - consolidated into guides/tools-pages/
│ └── README.md (redirects to guides/tools-pages/)
├── pages/ # Page documentation
│ ├── comparison-pages/
│ ├── product-pages/
│ └── [other page types]/
├── competitors/ # Competitor profiles
│ ├── COMPETITORS_INVENTORY.md
│ └── [competitor-slug]-profile.md
├── product-features/ # Product feature docs
│ ├── PRODUCT_FEATURES_INVENTORY.md
│ └── [feature-slug]-documentation.md
└── blog/ # Blog inventory
└── BLOG_INVENTORY.md

docs/guides/tools-pages/ # Consolidated tools documentation
├── testing/ # Testing files (moved from docs/tools/)
│ └── arbeitslosengeld-rechner/
├── TOOLS_INVENTORY.md
└── [tool-slug]-documentation.md

docs/archive/ # Archived/outdated content
├── completed-projects/ # Completed project summaries
├── 2025/
│ ├── testing-results/ # Old testing results
│ ├── backups/ # Backup files
│ └── implementation-reports/ # Completed implementations
└── [year]/ # Year-specific archives

````

## Metadata Headers

### For Key Files

Add metadata at the top:

```markdown
---
title: Document Title
description: Brief description
last_updated: YYYY-MM-DD
category: tools|pages|competitors|features
---
````

## Validation Checklist

Before committing documentation:

- [ ] File name follows conventions
- [ ] "Last Updated" date is accurate and current
- [ ] All internal links work
- [ ] Cross-references are included
- [ ] Code examples are formatted correctly
- [ ] Content is clear and concise
- [ ] Related documentation is linked

## Related Cursor Rules

When working with documentation, the following Cursor rules apply:

- **[global.mdc](.cursor/rules/global.mdc)** - Planning requirements, research checklists, documentation standards (always applies)
- **[shared-patterns.mdc](.cursor/rules/shared-patterns.mdc)** - Universal validation checklist and shared patterns
- **[date-management.mdc](.cursor/rules/date-management.mdc)** - Date management standards and guidelines
- **[content-writing.mdc](.cursor/rules/content-writing.mdc)** - Content writing guidelines and best practices

## Related Documentation

- **[Documentation Maintenance Process](DOCUMENTATION_MAINTENANCE_PROCESS.md)** - Update workflows
- **[Date Management Guidelines](DATE_MANAGEMENT_GUIDELINES.md)** - Date standards
- **[Contributing Guidelines](CONTRIBUTING.md)** - Contribution process