# Item 7: Documentation Systems

**Priority:** High  
**Target:** Production Launch  
**Last Updated:** December 11, 2025

---

## Overview

Create comprehensive documentation systems including in-app help, marketing site documentation, API references, integration guides, workflow guides, and FAQs. Ensure users can self-serve for common questions and technical implementation.

---

## Current State Analysis

### Existing Documentation

**Location:** `docs/` folder in repository

**Current Structure:**
- System architecture docs
- Backend models and services
- Frontend components
- API references (partial)
- Deployment guides

**Issues:**
- Documentation scattered and incomplete
- No user-facing help system
- No in-app contextual help
- API documentation not published
- Integration guides missing
- FAQ not comprehensive

---

## Required Documentation Types

### A. In-App Documentation

**Purpose:** Help users within the application

---

#### 1. Contextual Help System

**Implementation:** Floating help icon + modal

**Location:** Every major page

**Features:**
- Help icon in page header (question mark)
- Click to open help modal
- Modal contains:
  - Page overview
  - Key features explanation
  - Quick tips
  - Link to full documentation
  - Video tutorial (if available)

**Example (Keywords Page):**

```
┌────────────────────────────────────────────────┐
│ Help: Keywords Page                        [×] │
├────────────────────────────────────────────────┤
│ Overview                                       │
│ ───────────────────────────────────────────── │
│ The Keywords page is where you extract and    │
│ manage SEO keywords for your content strategy.│
│                                                │
│ Key Features                                   │
│ ───────────────────────────────────────────── │
│ • Add Keywords: Manually or import from CSV   │
│ • Cluster: Group keywords semantically        │
│ • Volume & Difficulty: SEO metrics            │
│ • Status: Track mapping progress              │
│                                                │
│ Quick Tips                                     │
│ ───────────────────────────────────────────── │
│ 💡 Start with 20-50 keywords                  │
│ 💡 Run clustering after adding keywords       │
│ 💡 Use filters to find unmapped keywords      │
│                                                │
│ [Watch Tutorial Video] [View Full Docs]       │
└────────────────────────────────────────────────┘
```

**Content per Page:**

| Page | Overview | Key Actions | Tips |
|------|----------|-------------|------|
| **Keywords** | Extract and manage keywords | Add, Import, Cluster | Start with 20-50, run clustering |
| **Clusters** | View keyword groups | Edit, Generate Ideas | Review cluster names for clarity |
| **Ideas** | Content ideas from clusters | Edit, Convert to Tasks | Check word count estimates |
| **Tasks** | Content generation queue | Generate Content | Monitor credit usage |
| **Content** | Review generated articles | Edit, Publish | Optimize before publishing |
| **Images** | Manage article images | Generate Images | Check image relevance |
| **Automation** | Automate workflows | Configure, Run | Start with small batches |

---

#### 2. Onboarding Tour

**Component:** `frontend/src/components/onboarding/OnboardingTour.tsx` (NEW)

**Purpose:** First-time user walkthrough

**Trigger:** First login or first page visit

**Steps:**

**Step 1: Welcome**
- "Welcome to IGNY8!"
- "Let's take a quick tour to get you started"
- [Start Tour] [Skip]

**Step 2: Setup**
- "First, connect your site and configure settings"
- Points to Setup menu
- [Next]

**Step 3: Keywords**
- "Add keywords to start planning content"
- Points to Keywords page
- [Next]

**Step 4: Planner Workflow**
- "Use the Planner to organize keywords and generate ideas"
- Shows workflow diagram
- [Next]

**Step 5: Writer Workflow**
- "The Writer generates content from your ideas"
- Shows content generation process
- [Next]

**Step 6: Credits**
- "Each AI operation uses credits. Monitor usage here."
- Points to credits display
- [Next]

**Step 7: Done**
- "You're all set! Start by adding keywords."
- [Go to Keywords] [Finish Tour]

**Implementation:**
- Use library like `react-joyride` or custom tooltips
- Store tour completion in localStorage
- Option to restart tour from settings

---

#### 3. Tooltips on UI Elements

**Coverage:**

| Element | Tooltip Text |
|---------|--------------|
| Cluster button | "Group keywords by semantic similarity using AI" |
| Generate Ideas button | "Create content ideas from selected clusters" |
| Generate Content button | "Write articles from tasks using AI" |
| Generate Images button | "Create images from prompts using AI" |
| Word count field | "Target word count: 500, 1000, or 1500 words" |
| Content structure dropdown | "Article format: guide, review, listicle, etc." |
| Status badges | "Current processing status: pending, completed, failed" |
| Credit balance | "Remaining credits for AI operations" |
| Site selector | "Select site for this workflow" |
| Sector selector | "Select industry sector for context" |

**Implementation:**
- Use Tooltip component (from Item 4)
- Add to all icons, dropdowns, status indicators
- Keep text brief (1-2 sentences)

---

#### 4. Inline Help Text

**Placement:** Under form fields

**Examples:**

```tsx
<FormField label="Keywords">
  <input type="text" placeholder="Enter keyword" />
  <InlineHelp>
    Use lowercase, no special characters. 
    Separate multiple keywords with commas.
  </InlineHelp>
</FormField>

<FormField label="Word Count">
  <select>
    <option value="500">500 words</option>
    <option value="1000">1000 words</option>
    <option value="1500">1500 words</option>
  </select>
  <InlineHelp>
    Choose article length. Affects credit usage (1 credit per 100 words).
  </InlineHelp>
</FormField>
```

---

### B. Marketing Site Documentation

**Purpose:** Public-facing help center

**Location:** `/help` or `/docs` section of marketing site

---

#### 1. Help Center Structure

**Homepage:** `/help`

**Categories:**

```
Help Center
├── Getting Started
│   ├── Creating Your Account
│   ├── Setting Up Your First Site
│   ├── Understanding Credits
│   └── Quick Start Guide
├── Planner Module
│   ├── Adding Keywords
│   ├── Keyword Clustering
│   ├── Generating Ideas
│   └── Content Planning Strategy
├── Writer Module
│   ├── Creating Tasks
│   ├── Generating Content
│   ├── Generating Images
│   ├── Editing Content
│   └── Publishing to WordPress
├── Automation
│   ├── Setting Up Automation
│   ├── Configuring Stages
│   ├── Monitoring Progress
│   └── Troubleshooting Automation
├── Integrations
│   ├── WordPress Setup
│   ├── Google Search Console
│   ├── API Integration
│   └── OAuth Connections
├── Billing & Plans
│   ├── Understanding Plans
│   ├── Managing Credits
│   ├── Upgrading Your Plan
│   └── Invoices and Payments
├── Troubleshooting
│   ├── Common Errors
│   ├── API Issues
│   ├── Publishing Problems
│   └── Credit Deduction Issues
└── FAQ
    ├── General Questions
    ├── Pricing Questions
    ├── Technical Questions
    └── Account Questions
```

**Each article contains:**
- Title
- Last updated date
- Estimated reading time
- Content with screenshots/gifs
- Related articles
- "Was this helpful?" feedback
- Contact support link

---

#### 2. API Documentation

**Location:** `/docs/api` or `/api-docs`

**Format:** OpenAPI/Swagger or similar

**Sections:**

**Authentication**
- Getting API keys
- Authentication methods (Bearer token)
- Rate limits
- Error codes

**Endpoints by Module:**

**Planner API**
- `GET /api/v1/planner/keywords/` - List keywords
- `POST /api/v1/planner/keywords/` - Create keyword
- `POST /api/v1/planner/keywords/auto_cluster/` - Trigger clustering
- `GET /api/v1/planner/clusters/` - List clusters
- `POST /api/v1/planner/ideas/generate/` - Generate ideas

**Writer API**
- `GET /api/v1/writer/tasks/` - List tasks
- `POST /api/v1/writer/tasks/` - Create task
- `POST /api/v1/writer/tasks/{id}/generate_content/` - Generate content
- `GET /api/v1/writer/content/` - List content
- `POST /api/v1/writer/content/{id}/generate_images/` - Generate images

**Automation API**
- `GET /api/v1/automation/runs/` - List runs
- `POST /api/v1/automation/runs/start/` - Start automation
- `POST /api/v1/automation/runs/{id}/pause/` - Pause automation
- `POST /api/v1/automation/runs/{id}/resume/` - Resume automation

**Billing API**
- `GET /api/v1/billing/credits/` - Get credit balance
- `GET /api/v1/billing/usage/` - Get usage logs
- `GET /api/v1/billing/invoices/` - List invoices

**System API**
- `GET /api/v1/system/prompts/` - List prompts
- `GET /api/v1/system/settings/` - Get settings
- `POST /api/v1/system/settings/` - Update settings

**For Each Endpoint Document:**
- HTTP method and path
- Description
- Authentication required
- Request parameters
- Request body schema
- Response schema
- Example request
- Example response
- Possible error codes

**Example Entry:**

```markdown
## Generate Content

`POST /api/v1/writer/tasks/{id}/generate_content/`

Generate AI content for a specific task.

### Authentication
Required. Bearer token.

### Parameters
- `id` (path, required): Task ID

### Request Body
```json
{
  "word_count": 1000,
  "content_structure": "article"
}
```

### Response
```json
{
  "status": "success",
  "task_id": "celery-task-uuid",
  "message": "Content generation started"
}
```

### Errors
- `400 Bad Request`: Invalid parameters
- `403 Forbidden`: Insufficient credits
- `404 Not Found`: Task not found
- `429 Too Many Requests`: Rate limit exceeded

### Credit Cost
1 credit per 100 words (10 credits for 1000-word article)
```

---

#### 3. Integration Guides

**Purpose:** Step-by-step setup instructions

---

**A. WordPress Integration Guide**

**Location:** `/docs/integrations/wordpress`

**Sections:**

1. **Prerequisites**
   - WordPress 5.0+ required
   - Admin access
   - REST API enabled

2. **Installation Steps**
   - Install WordPress plugin (if applicable) or use API
   - Generate application password in WordPress
   - Enter credentials in IGNY8

3. **Configuration**
   - Set default post type
   - Set default category
   - Configure SEO settings
   - Set featured image rules

4. **Publishing Workflow**
   - How content syncs
   - How images are uploaded
   - How meta tags are set
   - How to schedule posts

5. **Troubleshooting**
   - Connection errors
   - Publishing failures
   - Image upload issues
   - Permission problems

6. **Screenshots**
   - Annotated screenshots for each step

---

**B. Google Search Console Integration**

**Location:** `/docs/integrations/google-search-console`

**Sections:**

1. **Setup**
   - OAuth authentication
   - Site verification
   - Permission requirements

2. **Keyword Import**
   - Importing search queries
   - Volume and position data
   - Filtering options

3. **Syncing**
   - Auto-sync frequency
   - Manual sync
   - Data refresh

4. **Troubleshooting**
   - OAuth errors
   - Permission issues
   - Data not syncing

---

**C. API Integration Guide**

**Location:** `/docs/integrations/api`

**Sections:**

1. **Getting Started**
   - Generating API keys
   - Testing with cURL
   - Rate limits

2. **Authentication**
   - Bearer token usage
   - Security best practices

3. **Common Workflows**
   - Automated keyword import
   - Bulk content generation
   - Publishing pipelines

4. **Webhooks** (if implemented)
   - Setting up webhooks
   - Event types
   - Payload structure

5. **Code Examples**
   - Python example
   - JavaScript example
   - PHP example

---

#### 4. Workflow Guides

**Purpose:** End-to-end workflow documentation

---

**A. Planner to Writer SEO Flow**

**Location:** `/docs/workflows/seo-content-flow`

**Content:**

**Step 1: Keyword Research**
- Add keywords manually or import from GSC
- Aim for 50-100 keywords per topic area
- Include variety of search volumes

**Step 2: Keyword Clustering**
- Run AI clustering on keywords
- Review cluster names and descriptions
- Merge or split clusters as needed

**Step 3: Idea Generation**
- Select clusters
- Generate content ideas
- Review cluster hub vs supporting ideas
- Check word count estimates

**Step 4: Task Creation**
- Convert ideas to tasks
- Set word count and structure
- Organize by priority

**Step 5: Content Generation**
- Generate content for tasks
- Monitor credit usage
- Review generated content

**Step 6: Image Generation**
- Generate image prompts
- Generate images from prompts
- Review and approve images

**Step 7: Publishing**
- Edit content as needed
- Publish to WordPress
- Monitor performance

**Screenshots/Videos for each step**

---

**B. Automation Workflow**

**Location:** `/docs/workflows/automation`

**Content:**

**Overview**
- What automation does
- When to use it
- Prerequisites

**Configuration**
- Stage batch sizes
- Delays between stages
- Credit budgets

**Execution**
- Starting a run
- Monitoring progress
- Pausing and resuming

**Results**
- Reviewing output
- Handling failures
- Re-running stages

---

#### 5. Credit System Documentation

**Location:** `/docs/billing/credits`

**Sections:**

**How Credits Work**
- What credits are
- How they're used
- How to purchase

**Credit Costs**

| Operation | Credits | Example |
|-----------|---------|---------|
| Keyword Clustering | 10 | Cluster 50 keywords = 10 credits |
| Idea Generation | 15 per cluster | 3 clusters = 45 credits |
| Content Generation | 1 per 100 words | 1000-word article = 10 credits |
| Image Prompt Extraction | 3 | 1 article = 3 credits |
| Image Generation | 6 per image | 5 images = 30 credits |

**Credit Management**
- Viewing balance
- Monitoring usage
- Auto top-up
- Purchasing credits

**Rollover Policy**
- Monthly credits
- Expiration rules
- Unused credit handling

---

#### 6. Data Privacy & Security

**Location:** `/docs/security`

**Sections:**

**Data Storage**
- Where data is stored
- Data encryption
- Backup frequency

**Access Control**
- User roles and permissions
- Account isolation
- API security

**Compliance**
- GDPR compliance
- Data deletion
- Export your data

**Best Practices**
- Password requirements
- Two-factor authentication (if available)
- API key management

---

### C. FAQ System

**Purpose:** Quick answers to common questions

**Location:** `/help/faq` and in-app FAQ modal

---

#### FAQ Categories

**1. General Questions**

Q: What is IGNY8?
A: IGNY8 is an AI-powered content creation platform...

Q: How does the AI work?
A: We use advanced NLP and semantic AI...

Q: Is my content unique?
A: Yes, all content is generated fresh for you...

Q: Can I edit AI-generated content?
A: Yes, you have full control to edit...

---

**2. Pricing Questions**

Q: What happens when I run out of credits?
A: You can purchase more credits or upgrade your plan...

Q: Can I change plans mid-month?
A: Yes, you can upgrade anytime. Prorated refunds for downgrades...

Q: Do unused credits roll over?
A: Monthly credits expire at the end of your billing cycle...

Q: What's included in Enterprise?
A: Custom credit allocations, priority support, dedicated account manager...

Q: Is there a free trial?
A: Yes, 14-day free trial on paid plans, no credit card required...

Q: Can I cancel anytime?
A: Yes, cancel anytime from your account settings...

---

**3. Content Generation Questions**

Q: How long does content generation take?
A: Typically 10-30 seconds per 1000-word article...

Q: Can I control the writing style?
A: Yes, choose tone, structure, and use author profiles...

Q: What languages are supported?
A: Currently English, with more languages planned...

Q: Can I generate product descriptions?
A: Yes, select "product_page" content structure...

Q: How accurate is SEO optimization?
A: Content includes primary keywords, proper structure, and meta tags...

---

**4. Integration Questions**

Q: Which WordPress versions are supported?
A: WordPress 5.0 and above...

Q: Do I need a plugin?
A: No, uses WordPress REST API. Plugin optional for advanced features...

Q: Can I publish to multiple sites?
A: Yes, create multiple site connections...

Q: Does it work with WooCommerce?
A: Yes, can generate product descriptions and category content...

Q: Can I import from Google Docs?
A: Not directly, but you can copy/paste or import CSV...

---

**5. Technical Questions**

Q: Is there an API?
A: Yes, full REST API available on Growth plan and above...

Q: What are the rate limits?
A: API: 100 requests/minute. Content generation: No limit but subject to credits...

Q: Can I use webhooks?
A: Yes, webhook support for automation events (Enterprise)...

Q: How do I get API keys?
A: Generate from Settings > Integrations > API Access...

Q: Is there a mobile app?
A: Not yet, but the web app is mobile-responsive...

---

**6. Account & Billing Questions**

Q: How do I upgrade my plan?
A: Go to Settings > Billing > Upgrade Plan...

Q: What payment methods do you accept?
A: Credit/debit cards via Stripe, PayPal, bank transfer (Enterprise)...

Q: Can I get an invoice?
A: Yes, invoices are automatically generated and emailed...

Q: How do I add team members?
A: Settings > Team > Invite User (available on Starter and above)...

Q: Can I delete my account?
A: Yes, Settings > Account > Delete Account. Data deleted after 14 days...

---

## Implementation Plan

### Phase 1: In-App Help (Week 1-2)
1. ✅ Create contextual help component
2. ✅ Write help content for each page
3. ✅ Add help icons to all pages
4. ✅ Create onboarding tour component
5. ✅ Implement tour steps

### Phase 2: Help Center (Week 2)
1. ✅ Set up help center structure
2. ✅ Write Getting Started guides
3. ✅ Write module-specific guides
4. ✅ Create workflow documentation
5. ✅ Add screenshots and videos

### Phase 3: API Documentation (Week 2-3)
1. ✅ Document all API endpoints
2. ✅ Create code examples
3. ✅ Set up API documentation tool (Swagger/Redoc)
4. ✅ Test all endpoints
5. ✅ Publish API docs

### Phase 4: Integration Guides (Week 3)
1. ✅ Write WordPress integration guide
2. ✅ Write GSC integration guide
3. ✅ Write API integration guide
4. ✅ Create screenshots
5. ✅ Test guides with fresh account

### Phase 5: FAQ (Week 3)
1. ✅ Compile common questions
2. ✅ Write answers
3. ✅ Categorize questions
4. ✅ Create searchable FAQ interface
5. ✅ Add FAQ to help center and in-app

---

## Success Metrics

- ✅ Help content available for all major pages
- ✅ Onboarding tour completed by 70%+ of new users
- ✅ Help center covers 100% of core features
- ✅ API documentation complete for all endpoints
- ✅ Integration guides tested and validated
- ✅ FAQ answers top 50 common questions
- ✅ User support requests decrease by 40%
- ✅ Documentation feedback positive (thumbs up > 80%)

---

## Related Files Reference

### Frontend (NEW)
- `frontend/src/components/help/HelpModal.tsx`
- `frontend/src/components/onboarding/OnboardingTour.tsx`
- `frontend/src/pages/Help/` - Help center pages
- `frontend/src/pages/Docs/` - API documentation

### Content (NEW)
- `docs/help/` - Help center articles (Markdown)
- `docs/api/` - API documentation (OpenAPI spec)
- `docs/guides/` - Integration and workflow guides

### Backend
- API endpoint for serving documentation
- Search functionality for help center

---

## Notes

- Keep documentation up to date with product changes
- Use analytics to track which docs are most viewed
- Collect user feedback on helpfulness
- Consider video tutorials for complex workflows
- Plan for multilingual documentation (future)
- Consider community forum or knowledge base (future)
- Regular doc reviews (monthly or after major updates)
- Use simple language, avoid jargon
- Include lots of examples and screenshots
- Test documentation with actual users before launch
