Skill: Documents (Cross-Cutting & Multi-Format)

# Skill: Documents (Cross-Cutting & Multi-Format)

## Purpose

This skill is used to create comprehensive documentation for both technical and end-user audiences. It supports parallel generation of Markdown files (for repository/GitHub) and interactive HTML files (for browser-based manuals).

## Core Requirements

### 1. Multi-Format Output
Every documentation task should ideally generate four versions:
- `documentation.txt`: A concise, text-only overview for quick reading and AI context.
- `documentation.md`: High-quality Markdown for version control and GitHub READMEs.
- `documentation.html`: An interactive, premium documentation page with sidebar navigation.
- `documentation-landing-page.html`: A visual, high-end landing page to showcase the project/plugin.

### 2. Dynamic Design (Not Fixed Templates)
- **Do NOT follow a rigid template**: The Agent must **design** the documentation layout and content structure specifically for the project.
- **Synergy with ui-ux**: use of the `ui-ux` skill is **MANDATORY** for `documentation.html` and `documentation-landing-page.html`.

### 3. Standard Quality Structure (Mandatory)
To ensure clarity and completeness, the generated documentation MUST include:

#### A. Interactive Documentation (documentation.html)
1.  **Quick Start**: Clear steps to get running in < 2 minutes.
2.  **System Requirements**: OS, versions, dependencies.
3.  **Installation & Setup**: Detailed step-by-step guide.
4.  **Configuration**: Explanation of all settings (config files, UI settings).
5.  **Core Features**: Deep dive into each component found in `heraspec/specs/`.
6.  **Technical Reference**: (For Devs) API endpoints, Hooks, Filters, Functions.
7.  **Troubleshooting & FAQ**: Common issues and solutions.

#### B. Premium Landing Page (documentation-landing-page.html)
1.  **Hero Section**: High-impact headline and clear sub-headline.
2.  **Value Proposition**: Briefly explain "The Problem" vs "The Solution".
3.  **Feature Showcase**: A visual grid of key benefits with icons/images.
4.  **How It Works**: A simplified 1-2-3 step process of using the project.
5.  **CTA (Call to Action)**: Prominent buttons to "Get Started" or "View Docs".

### 4. Visual Excellence
- Use gradients, smooth animations (fade-in, slide), and premium fonts (e.g., Inter, Montserrat).
- The HTML documentation should feel like a modern SaaS dashboard or a high-end technical manual.

### 4. Project-Wide Scope
When tasked with generating documentation for the entire project:
- **Data Source**: Agent MUST read `heraspec/project.md` and ALL files in `heraspec/specs/`.
- **Synthesis**: Agent must combine information from all components and features into a unified manual.
- **Landing Page**: Should serve as the project homepage, summarizing the main value proposition and key features across all modules.

## Implementation Steps

### Step 1: Intelligence Gathering & Design Planning
1. **Analyze Project**: Scan all relevant `.md` files in the project. Understand the core purpose and technical details.
2. **Enforce UI/UX Dependency**:
   - Check if `heraspec/skills/ui-ux/` exists.
   - If missing: **Execute `heraspec skill add ui-ux`** immediately. Do NOT proceed with HTML generation until this skill is available.
3. **Define Design System**: Consult the `ui-ux` skill to establish a visual language (colors, fonts, animation styles).
4. **Plan Structures**: Outline what needs to go into the `.txt`, `.md`, and `.html` versions.

### Step 2: Constructing Documentation Assets
1. **Compose documentation.txt & .md**: Focus on clarity and technical accuracy.
2. **Develop documentation.html**: Build a split-panel layout (Sidebar + Content). DO NOT just fill a template; **write the HTML/CSS/JS** needed to make it look premium and project-specific.
3. **Design documentation-landing-page.html**: Create a compelling Hero section and feature showcase. Link to the main docs.

## Required Input

- **Project Context**: The name of the plugin/project (e.g., "polyutilities").
- **Specs/Docs**: All existing documentation and specification files.
- **Design Guidelines**: Inputs from the `ui-ux` skill.

## Expected Output (Save to /documentations/)

**CRITICAL**: All files MUST be placed in a `/documentations` folder at the project root. If this folder does not exist, the Agent MUST create it first.

- `/documentations/documentation.txt`: Plain text overview.
- `/documentations/documentation.md`: Markdown version.
- `/documentations/documentation.html`: Interactive split-panel HTML.
- `/documentations/documentation-landing-page.html`: Visual landing page.
- `/documentations/style.css` & `/documentations/landing-style.css`: Custom-generated styles.
- `/documentations/script.js` & `/documentations/landing-script.js`: Interactive logic.

## Tone & Rules

- **Consistent Content**: The core information must be synchronized across all formats.
- **Design Autonomy**: The Agent is responsible for the final aesthetic and structural quality.
- **Visual Impact**: Documentation must WOW the user with its premium feel.

## Reference Templates
These are provided as starting points or inspiration. The Agent should feel free to expand or modify them to suit the project:

- `templates/documentation.html` - Base HTML documentation layout
- `templates/documentation-landing-page.html` - Premium Landing Page layout
- `templates/style.css` - Premium styles for HTML documentation
- `templates/landing-style.css` - Premium styles for Landing Page
- `templates/script.js` - Interactive logic for HTML documentation
- `templates/landing-script.js` - Interactive logic for Landing Page
- `templates/technical-doc-template.md` - Technical documentation
- `templates/user-guide-template.md` - User guide
- `templates/api-doc-template.md` - API documentation
- `templates/changelog-template.md` - Changelog template

## Links to Other Skills

- **ui-ux**: ESSENTIAL. Use this to determine the look and feel of the HTML documentation.
- **content-optimization**: Use to ensure the text is clear and professional.