# 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
Use lowercase, no special characters.
Separate multiple keywords with commas.
Choose article length. Affects credit usage (1 credit per 100 words).
```
---
### 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