# Documentation Templates

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

Standard templates for creating documentation across all content types. Use these templates to ensure consistency and completeness.

## Template Index

- [Competitor Profile Template](#competitor-profile-template)
- [Product Feature Template](#product-feature-template)
- [Comparison Page Template](#comparison-page-template)
- [Product Page Template](#product-page-template)
- [Industry Page Template](#industry-page-template)
- [Status File Template](#status-file-template)
- [System README Template](#system-readme-template)
- [Implementation Summary Template](#implementation-summary-template)
- [Guide Template](#guide-template)

**Note:** Tool documentation template already exists at `docs/guides/tools-pages/TOOL_DOCUMENTATION_TEMPLATE.md`.

---

## Competitor Profile Template

**File Location:** `docs/content/competitors/[competitor-slug]-profile.md`

```markdown
# [Competitor Name] Profile

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

## Basic Information

- **Competitor Name:** [Full name]
- **Slug:** [URL slug]
- **Website:** [Website URL]
- **Type:** Direct Competitor / Indirect Competitor / Content Competitor / Industry Leader
- **Status:** Active / Archived

## Overview

[Brief overview of the competitor, their market position, and relevance to Ordio]

## Key Features

### Core Features

- [Feature 1]
- [Feature 2]
- [Feature 3]

### Unique Selling Points

- [USP 1]
- [USP 2]

### Target Market

- [Target market description]

## Comparison with Ordio

### Strengths

- [Competitor strength 1]
- [Competitor strength 2]

### Weaknesses

- [Competitor weakness 1]
- [Competitor weakness 2]

### Ordio Advantages

- [Ordio advantage 1]
- [Ordio advantage 2]

## Pricing

- **Model:** [Pricing model]
- **Starting Price:** [Price]
- **Notes:** [Pricing notes]

## Market Position

- **Market Share:** [If known]
- **Geographic Focus:** [Regions]
- **Industry Focus:** [Industries]

## Related Documentation

- [Comparison Page Documentation](content/pages/comparison-pages/[competitor-slug]-documentation.md) (if exists)
- [Competitors Inventory](content/competitors/COMPETITORS_INVENTORY.md)
- [Direct Competitors List](content/competitors/DIRECT_COMPETITORS_LIST.md)

## Related Cursor Rules

- [comparison-pages-core.mdc](.cursor/rules/comparison-pages-core.mdc)
- [comparison-pages-content.mdc](../../.cursor/rules/comparison-pages-content.mdc)
- [shared-patterns.mdc](../../.cursor/rules/shared-patterns.mdc)
```

---

## Product Feature Template

**File Location:** `docs/content/product-features/[feature-slug]-documentation.md`

**Note:** This template follows task-oriented documentation best practices. Focus on user outcomes and real-world scenarios.

````markdown
# [Feature Name] Documentation

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

## Basic Information

- **Feature Name:** [Full name]
- **Slug:** [URL slug]
- **Status:** Available / Coming Soon / Beta
- **Related Product Pages:**
  - `v2/pages/[page-file].php`
  - Product page: https://www.ordio.com/[slug]

## Overview

[Brief overview of the feature, its purpose, and value proposition. Include key benefit statement.]

## Use Cases

[Provide 3-5 detailed, task-oriented use cases with scenarios, processes, and benefits.]

### [Use Case Name 1]

**Scenario:** [Real-world scenario description]

**Process:**

1. [Step 1: What user does]
2. [Step 2: What happens next]
3. [Step 3: Final outcome]

**Benefits:** [Specific outcome - e.g., "Reduces planning time from 4 hours to 1 hour per week"]

### [Use Case Name 2]

[Repeat structure for additional use cases]

## Target Audience

### Primary Users

**[User Role 1]:**

- [Responsibility/need]
- [Benefit they get]
- [How they use the feature]

**[User Role 2]:**

[Repeat for other primary users]

### Secondary Users

**[User Role]:**

- [How they benefit]
- [When they use it]

### Industries

**[Industry 1]:**

- [Why this industry benefits]
- [Specific use case]

[Repeat for other industries]

## Key Functionality

### Core Capabilities

- **[Capability 1]:** [Description of what it does and why it matters]
- **[Capability 2]:** [Description]
- **[Capability 3]:** [Description]

### Advanced Features

**[Feature Name 1]:**

- [Detailed description]
- [When to use it]
- [Benefits]

**[Feature Name 2]:**

[Repeat for advanced features]

## Technical Implementation

### File Structure

**Frontend Files:**

- **PHP:** `v2/pages/[page-file].php` (~[lines] lines)
  - [Brief description of what the file contains]
- **JavaScript:** `v2/js/[js-file].js` (if exists)
  - [Description of JS functionality]
- **CSS:** `v2/css/product-pages.css` or `[feature-specific].css`
  - [Styling information]

**Dependencies:**

**Backend Systems:**

- [System 1: What it provides]
- [System 2: Integration details]

**External Integrations:**

- [Integration 1: Purpose and how it works]
- [Integration 2: Details]

**Frontend Libraries:**

- [Library 1: Purpose]
- [Library 2: Purpose]

### API Endpoints

[If applicable, document API endpoints]

**Endpoint Category:**

- `GET /api/[endpoint]` - [Purpose and description]
- `POST /api/[endpoint]` - [Purpose and description]

[Include request/response examples if available]

## User Experience

### Detailed User Flow

#### Flow 1: [Primary User Task]

1. **Access Feature:**

   - [How user accesses the feature]
   - [What they see initially]

2. **Perform Action:**

   - [Step-by-step process]
   - [What happens at each step]

3. **Complete Task:**
   - [Final steps]
   - [Outcome/confirmation]

#### Flow 2: [Secondary User Task]

[Repeat for other important flows]

### UI Components

**[Component Name]:**

- **Layout:** [Description of layout]
- **Elements:** [What's included]
- **Interactions:** [How users interact with it]
- **Visual Design:** [Styling notes if relevant]

[Repeat for other UI components]

## Visual Documentation

### Screenshots

**Dashboard View:**

- **File:** `/v2/img/screenshots/[feature]-dashboard.webp`
- **Alt Text:** "[Feature name] dashboard showing [key elements]"
- **Caption:** [What the screenshot demonstrates]

**Mobile View:**

- **File:** `/v2/img/screenshots/[feature]-mobile.webp`
- **Alt Text:** "[Feature name] mobile interface"
- **Caption:** [Mobile-specific information]

### Diagrams

**User Flow Diagram:**

- **File:** `/v2/img/diagrams/[feature]-user-flow.svg`
- **Description:** [What the diagram shows]
- **Use Case:** [When to reference this diagram]

**Integration Diagram:**

- **File:** `/v2/img/diagrams/[feature]-integration.svg`
- **Description:** [How feature integrates with other systems]

## Code Examples

[If applicable, include code examples]

### Example 1: [Simple Use Case]

```php
// Example: [What this code does]
// Prerequisites: [What's needed before this]
$example = new Example([
    'property' => 'value'
]);
$example->execute();
```
````

**Explanation:** [What the code does and why]

### Example 2: [Advanced Use Case]

[More complex example with comments]

## Maintenance

### Update Schedule

- **Regular updates:** [Frequency - e.g., Monthly feature enhancements]
- **Compliance updates:** [When - e.g., Quarterly updates for labor law changes]
- **Bug fixes:** [When - e.g., As needed based on user feedback]

### Common Updates

- **[Update Type 1]:** [What changes, when, why]
- **[Update Type 2]:** [Details]

## Related Documentation

- [Product Pages Inventory](content/pages/product-pages/PRODUCT_PAGES_INVENTORY.md)
- [Product Features Inventory](../PRODUCT_FEATURES_INVENTORY.md)
- [Related Feature Documentation](../[related-feature]-documentation.md) (if exists)

## Related Cursor Rules

- [product-pages.mdc](.cursor/rules/product-pages.mdc)
- [shared-patterns.mdc](.cursor/rules/shared-patterns.mdc)
- [global.mdc](.cursor/rules/global.mdc)

````

### Template Validation Checklist

Before finalizing documentation, verify:

- [ ] All sections complete (no "To be documented" placeholders)
- [ ] Use cases include scenarios, processes, and benefits
- [ ] Target audience clearly defined (primary/secondary users, industries)
- [ ] Technical implementation includes all relevant files and dependencies
- [ ] User flows are step-by-step and clear
- [ ] UI components described in detail
- [ ] Visual documentation planned/created (screenshots, diagrams)
- [ ] Code examples included if applicable
- [ ] Links validated (internal and external)
- [ ] "Last Updated" date accurate
- [ ] Content matches actual product page
- [ ] Cross-references to related documentation present

---

## Comparison Page Template

**File Location:** `docs/content/pages/comparison-pages/[competitor-slug]-documentation.md`

```markdown
# [Competitor Name] Comparison Page Documentation

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

## Basic Information

- **Competitor Name:** [Full name]
- **Slug:** [URL slug]
- **PHP File:** `v2/pages/compare_[slug].php`
- **Template:** `compare_template_details.php` / `compare_template_nodetails.php`
- **Status:** Published / Draft

## Page Structure

### Hero Section

- **Headline:** [H1 text]
- **Description:** [Hero description]
- **CTA:** [Call-to-action text]

### Comparison Table

- **Features Compared:** [List of features]
- **Ordio Advantages:** [Highlighted advantages]

### Content Sections

- [Section 1]
- [Section 2]
- [Section 3]

## Content Strategy

### Messaging

- [Key message 1]
- [Key message 2]

### SEO Focus

- **Primary Keyword:** [Keyword]
- **Secondary Keywords:** [Keywords]

## Maintenance

### Update Triggers

- [Trigger 1]
- [Trigger 2]

### Content Updates

- [Update type 1]
- [Update type 2]

## Related Documentation

- [Competitor Profile](content/competitors/[competitor-slug]-profile.md)
- [Comparison Pages Guide](../../guides/comparison-pages/COMPARISON_PAGES_GUIDE.md)
- [Comparison Pages Inventory](../COMPARISON_PAGES_INVENTORY.md)

## Related Cursor Rules

- [comparison-pages-core.mdc](../../../../../.cursor/rules/comparison-pages-core.mdc)
- [comparison-pages-content.mdc](../../../../../.cursor/rules/comparison-pages-content.mdc)
- [shared-patterns.mdc](../../../../../.cursor/rules/shared-patterns.mdc)
````

---

## Product Page Template

**File Location:** `docs/content/pages/product-pages/[product-slug]-documentation.md`

```markdown
# [Product Name] Page Documentation

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

## Basic Information

- **Product Name:** [Full name]
- **Slug:** [URL slug]
- **PHP File:** `v2/pages/product_[slug].php`
- **Status:** Published / Draft

## Page Structure

### Hero Section

- **Headline:** [H1 text]
- **Description:** [Hero description]
- **CTA:** [Call-to-action text]

### Feature Sections

- [Feature section 1]
- [Feature section 2]
- [Feature section 3]

### Use Cases

- [Use case 1]
- [Use case 2]

## Content Strategy

### Messaging

- [Key message 1]
- [Key message 2]

### SEO Focus

- **Primary Keyword:** [Keyword]
- **Secondary Keywords:** [Keywords]

## Maintenance

### Update Triggers

- [Trigger 1]
- [Trigger 2]

## Related Documentation

- [Product Feature Documentation](content/product-features/[feature-slug]-documentation.md)
- [Product Pages Inventory](../PRODUCT_PAGES_INVENTORY.md)

## Related Cursor Rules

- [product-pages.mdc](../../../../../.cursor/rules/product-pages.mdc)
- [shared-patterns.mdc](../../../../../.cursor/rules/shared-patterns.mdc)
- [global.mdc](../../../../../.cursor/rules/global.mdc)
```

---

## Industry Page Template

**File Location:** `docs/content/pages/industry-pages/[industry-slug]-documentation.md`

```markdown
# [Industry Name] Page Documentation

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

## Basic Information

- **Industry Name:** [Full name]
- **Slug:** [URL slug]
- **PHP File:** `v2/pages/industry_[slug].php`
- **Status:** Published / Draft

## Page Structure

### Hero Section

- **Headline:** [H1 text]
- **Description:** [Hero description]
- **CTA:** [Call-to-action text]

### Industry-Specific Content

- [Content section 1]
- [Content section 2]
- [Content section 3]

### Use Cases

- [Industry use case 1]
- [Industry use case 2]

## Content Strategy

### Messaging

- [Key message 1]
- [Key message 2]

### SEO Focus

- **Primary Keyword:** [Keyword]
- **Secondary Keywords:** [Keywords]

## Maintenance

### Update Triggers

- [Trigger 1]
- [Trigger 2]

## Related Documentation

- [Industry Pages Inventory](../INDUSTRY_PAGES_INVENTORY.md)

## Related Cursor Rules

- [industry-pages.mdc](../../../../../.cursor/rules/industry-pages.mdc)
- [shared-patterns.mdc](../../../../../.cursor/rules/shared-patterns.mdc)
- [global.mdc](../../../../../.cursor/rules/global.mdc)
```

---

## Template Usage Guidelines

### When to Use Templates

1. **Creating new documentation** - Always use the appropriate template
2. **Standardizing existing docs** - Update existing docs to match templates
3. **Ensuring completeness** - Templates ensure all sections are covered

### Template Customization

- **Required sections** - Must be included in all documentation
- **Optional sections** - Include if relevant to the specific content
- **Custom sections** - Add if needed for specific content types

### Quality Checklist

Before finalizing documentation:

- [ ] All required sections completed
- [ ] Cross-references added
- [ ] Related Cursor Rules section included
- [ ] "Last Updated" date accurate (use `date +%Y-%m-%d`)
- [ ] File naming follows conventions
- [ ] Added to appropriate inventory file

---

## Status File Template

**File Location:** `docs/[system-directory]/FINAL_STATUS.md` or `PROJECT_STATUS.md`

**Note:** Only one status file per directory. Use `FINAL_STATUS.md` for completed systems, `PROJECT_STATUS.md` for active projects.

```markdown
# [System/Project Name] - Final Status

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

**Status:** ✅ Complete and Operational / ⏳ In Progress / 📋 Planned

## Overview

[Brief overview of the system/project, its purpose, and current state]

## System Status

### ✅ [Major Component 1] - COMPLETE (YYYY-MM-DD)

- **[Feature/Component]:** [Description and status]
- **[Feature/Component]:** [Description and status]

### ⏳ [Major Component 2] - IN PROGRESS

- **[Feature/Component]:** [Current status and progress]
- **[Next Steps]:** [What's being worked on]

### 📋 [Major Component 3] - PLANNED

- **[Feature/Component]:** [Planned features]
- **[Timeline]:** [Expected completion date if known]

## Key Metrics

- **[Metric 1]:** [Value] - [Context/explanation]
- **[Metric 2]:** [Value] - [Context/explanation]

## Recent Updates

### [Date] - [Update Title]

- [Change description]
- [Impact/benefit]

## Related Documentation

- **[System Guide](README.md)** - Complete system documentation
- **[Implementation Summary](IMPLEMENTATION_SUMMARY.md)** - Implementation details (if exists)
- **[Next Steps](NEXT_STEPS.md)** - Future actions and improvements

## Related Cursor Rules

- **[system-rule.mdc](../../.cursor/rules/[system]-rule.mdc)** - System-specific patterns
- **[shared-patterns.mdc](../../.cursor/rules/shared-patterns.mdc)** - Universal patterns
- **[global.mdc](../../.cursor/rules/global.mdc)** - Planning requirements (always applies)
```

---

## System README Template

**File Location:** `docs/systems/[system-name]/README.md` or `docs/[section]/README.md`

**Purpose:** Main index and overview for a system or documentation section.

```markdown
# [System Name] Documentation

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

Complete documentation for [system name], covering [main topics covered].

## Related Cursor Rules

When working with [system name], the following Cursor rules apply:

- **[[system]-rule.mdc](../../../.cursor/rules/[system]-rule.mdc)** - [Description]
- **[shared-patterns.mdc](../../../.cursor/rules/shared-patterns.mdc)** - Universal patterns
- **[global.mdc](../../../.cursor/rules/global.mdc)** - Planning requirements (always applies)

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../ai/RULE_TO_DOC_MAPPING.md) for complete rule-to-documentation mapping.

## Overview

[Brief overview of the system, its purpose, and key features]

## Documentation Files

### Core Documentation

- **[Documentation File 1](FILE_1.md)** - [Description]
- **[Documentation File 2](FILE_2.md)** - [Description]

### Guides

- **[Guide 1](guides/GUIDE_1.md)** - [Description]
- **[Guide 2](guides/GUIDE_2.md)** - [Description]

### Reference

- **[Reference 1](reference/REFERENCE_1.md)** - [Description]

## Quick Start

1. [Step 1: What to do first]
2. [Step 2: Next action]
3. [Step 3: Final step]

## Key Concepts

### [Concept 1]

[Explanation of concept 1]

### [Concept 2]

[Explanation of concept 2]

## Common Tasks

### [Task 1]

[How to perform task 1]

### [Task 2]

[How to perform task 2]

## Status

- **Current Status:** [Status]
- **Last Updated:** YYYY-MM-DD
- **See:** [FINAL_STATUS.md](FINAL_STATUS.md) for complete status

## Related Documentation

- **[Status File](FINAL_STATUS.md)** - Current system status
- **[Next Steps](NEXT_STEPS.md)** - Future improvements
- **[Related System](../[related-system]/README.md)** - Related system documentation
```

---

## Implementation Summary Template

**File Location:** `docs/[system-directory]/IMPLEMENTATION_SUMMARY.md`

**Purpose:** Document implementation details for active projects. Archive when project is complete.

```markdown
# [Project Name] - Implementation Summary

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

**Status:** ✅ Complete / ⏳ In Progress / 📋 Planned

## Overview

[Brief overview of what was implemented, why, and current status]

## Implementation Details

### Phase 1: [Phase Name]

**Status:** ✅ Complete / ⏳ In Progress

**What Was Done:**

- [Implementation detail 1]
- [Implementation detail 2]

**Files Changed:**

- `path/to/file1.php` - [What changed]
- `path/to/file2.js` - [What changed]

**Dependencies:**

- [Dependency 1] - [Purpose]
- [Dependency 2] - [Purpose]

### Phase 2: [Phase Name]

[Repeat structure for additional phases]

## Technical Implementation

### Architecture

[High-level architecture description]

### Key Components

- **[Component 1]:** [Description and purpose]
- **[Component 2]:** [Description and purpose]

### Data Flow

[Description of how data flows through the system]

## Testing

### Test Coverage

- [Test type 1]: [Status]
- [Test type 2]: [Status]

### Test Results

[Summary of test results]

## Deployment

### Deployment Steps

1. [Step 1]
2. [Step 2]

### Rollback Plan

[How to rollback if needed]

## Known Issues

- [Issue 1]: [Description and workaround]
- [Issue 2]: [Description and workaround]

## Future Improvements

- [Improvement 1]: [Description]
- [Improvement 2]: [Description]

## Related Documentation

- **[Status File](FINAL_STATUS.md)** - Current project status
- **[System Documentation](README.md)** - Complete system documentation
- **[Next Steps](NEXT_STEPS.md)** - Future actions

## Related Cursor Rules

- **[system-rule.mdc](../../.cursor/rules/[system]-rule.mdc)** - Implementation patterns
- **[shared-patterns.mdc](../../.cursor/rules/shared-patterns.mdc)** - Universal patterns
```

---

## Guide Template

**File Location:** `docs/guides/[guide-name].md` or `docs/[section]/guides/[guide-name].md`

**Purpose:** Step-by-step guide for completing a task or understanding a process.

```markdown
# [Guide Title]

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

[Brief description of what this guide covers and who it's for]

## Prerequisites

Before following this guide, ensure you have:

- [Prerequisite 1]
- [Prerequisite 2]
- [Prerequisite 3]

## Overview

[High-level overview of the process or concept]

## Step-by-Step Instructions

### Step 1: [Step Name]

[Detailed instructions for step 1]

**Example:**

```[language]
[Code example if applicable]
```

**Expected Result:** [What should happen after this step]

### Step 2: [Step Name]

[Detailed instructions for step 2]

### Step 3: [Step Name]

[Detailed instructions for step 3]

## Common Issues and Solutions

### Issue: [Common Issue]

**Solution:** [How to resolve]

### Issue: [Another Common Issue]

**Solution:** [How to resolve]

## Best Practices

- [Best practice 1]
- [Best practice 2]
- [Best practice 3]

## Validation Checklist

- [ ] [Validation item 1]
- [ ] [Validation item 2]
- [ ] [Validation item 3]

## Related Documentation

- **[Related Guide](related-guide.md)** - Related guide
- **[Reference Documentation](../reference/REFERENCE.md)** - Reference material
- **[System Documentation](systems/[system]/README.md)** - System documentation

## Related Cursor Rules

- **[relevant-rule.mdc](../../.cursor/rules/relevant-rule.mdc)** - Relevant patterns
- **[shared-patterns.mdc](../../.cursor/rules/shared-patterns.mdc)** - Universal patterns
```

---

## Related Documentation

- [Documentation Standards](DOCUMENTATION_STANDARDS.md) - File naming and structure
- [Documentation Maintenance Process](DOCUMENTATION_MAINTENANCE_PROCESS.md) - Update workflows
- [Documentation Completeness Report](DOCUMENTATION_COMPLETENESS_REPORT.md) - Missing documentation