salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6e2101d019c3ab1e91bf41ff5fb5c2a9705f088e
igny8/docs/PRE-LAUNCH/ITEM-7-DOCUMENTATION.md
IGNY8 VPS (Salman) a736bc3d34 pre-launch-final mods-docs
2025-12-11 07:20:21 +00:00

20 KiB
Raw Blame History

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:

<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:

## 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

{
  "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
Reference in New Issue View Git Blame Copy Permalink