# Tool Documentation Template

**Last Updated:** 2026-03-25

Standard template for documenting tools/calculators. Use this template for all tool documentation.

## Tool Overview

### Basic Information

- **Tool Name:** [Full name]
- **Slug:** [URL slug]
- **URL:** `https://www.ordio.com/tools/[slug]`
- **Status:** Available / Coming Soon
- **Last Updated:** YYYY-MM-DD

### Purpose

[What the tool does, who it's for, why it's useful]

### Use Cases

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

### Target Audience

[Primary users: employees, employers, HR professionals, etc.]

### Visual Description

**Hero Section:**

- Layout: [Description of hero section layout]
- Headline: [H1 text and styling]
- Description: [Description text and styling]
- Badge/CTA: [If applicable]

**Calculator Form:**

- Layout: [Grid layout, form structure]
- Styling: [Colors, borders, spacing]
- Form elements: [Input fields, buttons, selects appearance]
- Responsive behavior: [How it adapts to screen sizes]

**Result Display:**

- Layout: [How results are displayed]
- Cards/Sections: [Result card structure]
- Typography: [Font sizes, weights, colors]
- Visualizations: [Charts, graphs, if applicable]

### UI/UX Flow

**Initial Load:**

- [What user sees on page load]
- [Default values displayed]
- [Initial state of form]

**User Interaction Flow:**

1. [Step 1: User action]
2. [Step 2: System response]
3. [Step 3: Result display]
4. [Step 4: Additional actions]

**Mode Switching (if applicable):**

- [How users switch between modes]
- [Visual indicators of active mode]
- [State preservation during switching]

**Error Handling Flow:**

- [How errors are displayed]
- [Error message styling]
- [Error recovery process]

## Technical Documentation

### File Structure

- **PHP File:** `v2/pages/tools_[name].php`
- **JavaScript Files:**
  - `v2/js/tools-[name]-calculator.js` (if extracted)
  - Or inline in PHP file
- **CSS:** Uses shared `v2/css/tools-pages.css`

### Calculation Modes

[Single mode or multiple modes]

**Mode 1: [Name]**

- **Visual Description:** [What this mode looks like, how it's accessed]
- **Purpose:** [What this mode calculates]
- **Input Fields:**
  - Field 1: [Type, placeholder, default value, validation]
  - Field 2: [Type, placeholder, default value, validation]
  - [All fields documented]
- **Output Fields:**
  - Result 1: [Format, location, styling]
  - Result 2: [Format, location, styling]
  - [All outputs documented]
- **Formula:** [Mathematical formula]
- **Calculation Steps:**
  1. [Step 1]
  2. [Step 2]
  3. [Step 3]
- **Example:**
  - Input: [Values]
  - Calculation: [Steps]
  - Output: [Results]
- **Edge Cases:** [How edge cases are handled]

**Mode 2: [Name]** (if applicable)

- [Same structure as Mode 1]

### Constants and Thresholds

**2026 Values:**

- Constant 1: [value] (source)
- Constant 2: [value] (source)
- Threshold 1: [value] (source)

**Previous Values (for reference):**

- Constant 1: [2026 value]
- Constant 2: [2026 value]

### Validation Rules

- Input 1: min=[value], max=[value], step=[value]
- Input 2: format=[format], validation=[rule]

### Edge Cases Handled

- [Edge case 1]: [How it's handled]
- [Edge case 2]: [How it's handled]

### Dependencies

- External Libraries: [list]
- APIs: [list]
- Alpine.js: [version/usage]

### Code Organization

**File Structure:**

- PHP: [File path, size, structure]
- JavaScript: [File path(s), size, structure]
- CSS: [File path(s), size, structure]

**Modular Structure (if applicable):**

- Module 1: [Purpose, exports]
- Module 2: [Purpose, exports]
- Dependencies: [Module dependencies]

**Code Patterns:**

- [Pattern 1]: [Description]
- [Pattern 2]: [Description]

### Functions & Methods

**Main Component Function:**

- Function Name: [Name]
- Location: [file.js:line-range]
- Purpose: [What it does]
- Returns: [What it returns]

**Calculation Functions:**

- `functionName1()`: [Purpose, parameters, returns, location]
- `functionName2()`: [Purpose, parameters, returns, location]
- [All calculation functions documented]

**Helper Functions:**

- `helperFunction1()`: [Purpose, parameters, returns, location]
- `helperFunction2()`: [Purpose, parameters, returns, location]
- [All helper functions documented]

**Export Functions:**

- `exportExcel()`: [Purpose, parameters, data structure, location]
- `exportPDF()`: [Purpose, parameters, layout, location]
- `exportCSV()`: [Purpose, parameters, format, location]
- [All export functions documented]

**Utility Functions:**

- `formatCurrency()`: [Purpose, parameters, returns, location]
- `validateInput()`: [Purpose, parameters, returns, location]
- [All utility functions documented]

**Event Handlers:**

- `onInputChange()`: [Trigger, handler, location]
- `onCalculate()`: [Trigger, handler, location]
- `onExport()`: [Trigger, handler, location]
- [All event handlers documented]

### State Management

**Alpine.js State Variables:**

- `variable1`: [Type, purpose, initial value]
- `variable2`: [Type, purpose, initial value]
- [All state variables documented]

**Computed Properties:**

- `computedProperty1`: [Dependencies, calculation, purpose]
- `computedProperty2`: [Dependencies, calculation, purpose]
- [All computed properties documented]

**Watchers:**

- `$watch('variable')`: [What it watches, what it does]
- [All watchers documented]

**localStorage:**

- Key: `key_name`: [What's stored, when it's set, when it's read]
- [All localStorage keys documented]

**URL Parameters:**

- Parameter: `param_name`: [What it does, how it's parsed, how it's used]
- [All URL parameters documented]

## Calculation Logic

### Formula Documentation

**Primary Formula:**

```
[Formula in mathematical notation]
```

**Step-by-Step Process:**

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

### Example Calculation

**Input:**

- Input 1: [value]
- Input 2: [value]

**Calculation:**

```
[Step-by-step calculation]
```

**Expected Result:**

- Output 1: [value]
- Output 2: [value]

### Legal Basis

- [Law/Regulation 1]: [Reference]
- [Law/Regulation 2]: [Reference]

## Content Documentation

### Hero Section

- **H1:** [Text]
- **Description:** [Text]

### Educational Content Sections

1. **[Section Title]**

   - Content summary
   - Key points

2. **[Section Title]**
   - Content summary
   - Key points

### FAQ Section

- **Total FAQs:** [number]
- **FAQ Topics:**
  - [Topic 1]: [FAQ count]
  - [Topic 2]: [FAQ count]

**Sample FAQs:**

1. [Question]?

   - Answer summary

2. [Question]?
   - Answer summary

### Meta Tags

- **Title:** [Full title]
- **Description:** [Full description]
- **Keywords:** [List]

### Schema Markup

- WebApplication schema: [Yes/No]
- FAQPage schema: [Yes/No]
- HowTo schema: [Yes/No]
- BreadcrumbList schema: [Yes/No]

**Optional:** Store `@graph` JSON in `v2/includes/tools/{slug}/schema-graph.json`, include from the page head after validation; keep FAQ text identical to visible `<details>` (see [TOOLS_CONTENT_WORKFLOW.md](TOOLS_CONTENT_WORKFLOW.md) § PHP partials).

### Internal Linking

- Links to: [list of internal pages]
- Link count: [number]

## Change Log

### Update History

**2026-01-07:**

- Updated all 2026 values (constants, examples, content)
- Updated "Last Updated" date
- Removed "(pending verification)" notes
- Updated year references (2025 → 2026)

**Previous Updates:**

- [Date]: [Description of changes]
- [Date]: [Description of changes]

## Annual Update Checklist

**For Annual Updates (typically January):**

- [ ] Update "Last Updated" date
- [ ] Update constants section with new values
- [ ] Update example calculations with new values
- [ ] Update content sections (H1, descriptions, FAQs)
- [ ] Update 2026 Update Requirements section (mark complete)
- [ ] Remove any "(pending verification)" notes
- [ ] Verify all legal references are current
- [ ] Update meta tags if needed
- [ ] Update schema markup if needed
- [ ] Test all calculations with new values
- [ ] Document changes in change log

## 2026 Update Requirements

### Immediate Updates (Required for Jan 1, 2026)

**Constants/Values:**

- [ ] Constant 1: Update from [old] to [new]
- [ ] Constant 2: Update from [old] to [new]

**Content:**

- [ ] Update year references: "2025" → "2026"
- [ ] Update meta tags
- [ ] Update FAQs with 2026 information

**Priority:** High / Medium / Low

### Throughout 2026 Updates

**Scheduled Updates:**

- [Date]: [Update description]
- [Date]: [Update description]

### Monitoring Requirements

- [Source to monitor]: [What to check]
- [Frequency]: [How often]

## Testing

### Test Cases

**Normal Cases:**

- Test 1: [Description] → Expected: [Result]
- Test 2: [Description] → Expected: [Result]

**Edge Cases:**

- Edge case 1: [Description] → Expected: [Result]
- Edge case 2: [Description] → Expected: [Result]

### Code Analysis

**Key Functions Location:**

- Main component: [file.js:line-range]
- Calculation functions: [file.js:line-range]
- Export functions: [file.js:line-range]
- Helper functions: [file.js:line-range]

**Constants Location:**

- Calculation constants: [file.js:line-range]
- Configuration constants: [file.js:line-range]

**Calculation Logic Flow:**

1. [Step 1: Input received]
2. [Step 2: Validation]
3. [Step 3: Calculation]
4. [Step 4: Result formatting]
5. [Step 5: Display]

**State Management Flow:**

- Initialization: [How state is initialized]
- Updates: [How state is updated]
- Dependencies: [State dependencies]

**Event Handler Flow:**

- Input events: [How input events are handled]
- Calculation triggers: [How calculations are triggered]
- Export triggers: [How exports are triggered]

### Export Functionality

**Excel Export:**

- **Trigger:** [How Excel export is triggered]
- **Email Gating:** [If email is required, how it works]
- **Data Included:**
  - [Data field 1]
  - [Data field 2]
  - [All data fields documented]
- **Format:** [Excel structure, sheets, formatting]
- **File Name:** [Naming convention]
- **Function:** [Export function name and location]

**PDF Export:**

- **Trigger:** [How PDF export is triggered]
- **Email Gating:** [If email is required, how it works]
- **Content Included:**
  - [Content section 1]
  - [Content section 2]
  - [All content documented]
- **Layout:** [PDF layout, sections, styling]
- **File Name:** [Naming convention]
- **Function:** [Export function name and location]

**CSV Export:**

- **Trigger:** [How CSV export is triggered]
- **Email Gating:** [If email is required, how it works]
- **Data Included:**
  - [Data field 1]
  - [Data field 2]
  - [All data fields documented]
- **Format:** [CSV structure, delimiter, encoding]
- **File Name:** [Naming convention]
- **Function:** [Export function name and location]

**Email Gating Process:**

- **When Required:** [When email is collected]
- **Modal Display:** [How modal appears]
- **Email Validation:** [Validation rules]
- **Storage:** [How email is stored - localStorage]
- **Pre-filling:** [If email is pre-filled from previous sessions]
- **Error Handling:** [How email errors are handled]

### Sharing Functionality

**Share URL Generation:**

- **Function:** [Share function name and location]
- **Parameters Included:** [What parameters are included in URL]
- **URL Format:** [URL structure example]
- **Encoding:** [How parameters are encoded]

**Shareable Parameters:**

- `param1`: [What it represents, format]
- `param2`: [What it represents, format]
- [All shareable parameters documented]

**Share Restoration:**

- **Function:** [Restore function name and location]
- **Process:** [How URL parameters are parsed and applied]
- **State Restoration:** [How form state is restored]

**Social Sharing (if applicable):**

- **Platforms:** [Which platforms supported]
- **Share Content:** [What content is shared]
- **Implementation:** [How it's implemented]

### Results & Insights

**Result Display:**

- **Primary Results:** [Main results displayed]
- **Secondary Results:** [Additional results displayed]
- **Result Formatting:** [How results are formatted - currency, percentages, etc.]
- **Result Styling:** [Visual styling of results]

**Result Breakdowns:**

- **Breakdown 1:** [What's included, how it's displayed]
- **Breakdown 2:** [What's included, how it's displayed]
- [All breakdowns documented]

**Visualizations:**

- **Chart Type:** [If charts/graphs are used]
- **Chart Library:** [Which library is used]
- **Chart Data:** [What data is visualized]
- **Chart Styling:** [Visual styling]

**Insights Provided:**

- **Insight 1:** [What insight is provided, when]
- **Insight 2:** [What insight is provided, when]
- [All insights documented]

### Browser Testing Results

**Desktop Browsers:**

- **Chrome:** [Tested version, status, issues found]
- **Firefox:** [Tested version, status, issues found]
- **Safari:** [Tested version, status, issues found]
- **Edge:** [Tested version, status, issues found]

**Mobile Testing:**

- **iOS Safari:** [Tested version, device, status, issues]
- **Android Chrome:** [Tested version, device, status, issues]
- **Mobile UI Differences:** [How UI differs on mobile]
- **Mobile Interactions:** [Touch interactions, gestures]

**Responsive Design:**

- **Desktop (>1024px):** [Layout, behavior]
- **Tablet (768px-1024px):** [Layout, behavior]
- **Mobile (<768px):** [Layout, behavior]
- **Breakpoints:** [Specific breakpoints used]

**Accessibility:**

- **Keyboard Navigation:** [How keyboard navigation works]
- **Screen Reader:** [Screen reader compatibility]
- **ARIA Labels:** [ARIA implementation]
- **Focus Management:** [How focus is managed]
- **Color Contrast:** [Color contrast compliance]

**Performance:**

- **Page Load Time:** [Measured load time]
- **Calculation Speed:** [How fast calculations run]
- **Export Speed:** [How fast exports generate]
- **Large Data Handling:** [How large datasets are handled]

### Export Testing

- Excel: [Status, tested scenarios]
- PDF: [Status, tested scenarios]
- CSV: [Status, tested scenarios]

## Maintenance Notes

### Known Issues

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

### Future Improvements

- [Improvement 1]
- [Improvement 2]

### Related Tools

- [Related tool 1]: [Relationship]
- [Related tool 2]: [Relationship]

## References

### Official Sources

- [Source 1]: [URL]
- [Source 2]: [URL]

### Documentation Files

- [Related doc 1]: [Path]
- [Related doc 2]: [Path]