# LinkMesh FAQ Redesign — Architecture Analysis & Proposal ## 1. Current State Analysis ### 1.1 What Exists Now | Location | File | Content Type | Status | |----------|------|-------------|--------| | Plugin | [`admin/class-ailm-faq-tab.php`](../admin/class-ailm-faq-tab.php) | In-app help — 6 tabs with detailed module walkthroughs + screenshots | **Production** — but missing modules (Dashboard, Review Queue, Gutenberg Sidebar, PageRank) | | Landing | [`faq.html`](../../Downloads/project-bolt-sb1-zq57uuag/project/faq.html) | Presales FAQ — pricing, security, compatibility, support (17 questions, accordion UI, FAQPage schema) | **Production** | | Landing | [`documentation.html`](../../Downloads/project-bolt-sb1-zq57uuag/project/documentation.html) | Placeholder stub — "Documentation Portal" with dummy Quick Start / Auth / Rate Limits text | **Stub — needs full rewrite** | ### 1.2 Plugin Architecture — All Modules The plugin has these modules. The FAQ currently covers only **6 of 10**: | # | Module | In Current FAQ? | PHP Class | |---|--------|:---:|---| | 1 | **Dashboard** (Performance + Unified Table) | ❌ Missing | `class-ailm-dashboard-admin.php` | | 2 | **Bulk Settings** (General + Category Rules + Simulation) | ✅ "General Settings" | `class-ailm-settings-tab.php` | | 3 | **Orphan Rescue** | ✅ | `class-ailm-orphan-admin.php` | | 4 | **Keyword Intelligence** | ✅ | `class-ailm-ki-admin.php` | | 5 | **404 Scout** | ✅ | `class-ailm-scout-admin.php` | | 6 | **Click Stats** | ✅ | `class-ailm-clicks-admin.php` | | 7 | **Links Report** (old Stats tab) | ✅ "Links Report" | `class-ailm-stats-tab.php` | | 8 | **Review Queue** (Semantic Link Queue) | ❌ Missing | `class-ailm-review-queue-admin.php` | | 9 | **Semantic Engine** (AI Smart Link Generator modal) | ❌ Missing | `class-ailm-semantic-init.php` | | 10 | **Gutenberg Sidebar** (in-editor link panel) | ❌ Missing | `class-ailm-gutenberg-sidebar.php` | | 11 | **PageRank** (AILM Rank column) | ❌ Missing | `class-ailm-pagerank.php` | ### 1.3 Current FAQ Structure in Plugin ```php $sections = [ 'general' => 'General Settings', // Welcome + Bulk Settings walkthrough 'orphan' => 'Orphan Rescue', // 3-step rescue process 'reports' => 'Links Report', // Link equity distribution 'clicks' => 'Click Stats', // Click analytics 'ki' => 'Keyword Intelligence', // LSI / N-grams 'scout' => '404 Scout' // Broken link monitor ]; ``` Rendered as horizontal button-tabs switching content divs via jQuery. Each tab is a long-form tutorial with screenshots. --- ## 2. Strategic Decision (UPDATED) ### Original question: Should Plugin FAQ = Website Documentation? **Answer: NO. But there's a better approach.** Instead of maintaining two sets of documentation (in-plugin and on the website), the proposal is: ### ✅ New Strategy: Single Source of Truth — the Website ``` Plugin (WordPress) Landing (linkmesh.co) ┌─────────────────────────┐ ┌──────────────────────────────┐ │ │ │ │ │ LinkMesh → FAQ / Help │ │ documentation.html │ │ ┌───────────────────┐ │ │ ┌────────────────────────┐ │ │ │ │ │ │ │ 🚀 Quick Start │ │ │ │ 📖 Open Full │ │ │ │ 📖 Core Concepts │ │ │ │ Documentation ───┼──┼────────▶│ │ ⚙️ Module Guides │ │ │ │ (linkmesh.co/docs)│ │ │ │ 🔧 Advanced │ │ │ │ │ │ │ │ 🐛 Troubleshooting │ │ │ │ ❓ Quick FAQ │ │ │ │ 📝 Changelog │ │ │ │ (linkmesh.co/faq) │ │ │ └────────────────────────┘ │ │ └───────────────────┘ │ │ │ │ │ │ faq.html (presales FAQ) │ │ Links also added to: │ │ ┌────────────────────────┐ │ │ • Dashboard (header) │ │ │ 💰 Pricing & Billing │ │ │ • Each module page │ │ │ 🔒 Security & Privacy │ │ │ (header) │ │ │ 📞 Support │ │ └─────────────────────────┘ └──────────────────────────────┘ ``` ### Why this is the right call: 1. **Single Source of Truth**: Documentation lives in one place — the website. Any change is applied instantly, no plugin release needed. 2. **Zero duplication**: No need to sync PHP + i18n with static HTML. One codebase. 3. **SEO**: Website docs are indexed by Google and drive organic traffic. In-plugin docs (behind WordPress login) are invisible to search engines. 4. **Instant updates**: Edit a page on the website → users see changes immediately. With the plugin approach, you'd need a release cycle and user updates. 5. **Rich content**: Website can use videos, interactive elements, any JS libraries. Plugin is constrained by WordPress admin API and styles. 6. **Analytics**: Track via Google Analytics which documentation sections are most popular. 7. **Better UX**: User opens docs in a new browser tab — can view documentation and work in the plugin side by side. ### What changes in the plugin: Instead of a heavy FAQ page with 6+ tabs and hundreds of PHP lines — a lightweight hub page with external links: - **Current approach**: `class-ailm-faq-tab.php` — 448 lines of PHP, 6 tabs, jQuery, screenshots - **New approach**: A clean hub page with: - "📖 Open Full Documentation" button → `https://linkmesh.co/documentation.html` - "❓ Frequently Asked Questions" button → `https://linkmesh.co/faq.html` - Brief support info (`support@linkmesh.co`) - Bonus: "?" icons in each module page header linking to the relevant documentation section --- ## 3. Website Documentation Structure (documentation.html) A single reference portal. Structure: ``` documentation.html ├── 🚀 Quick Start │ ├── Installation │ ├── Activation & License Key │ └── First Link in 5 Minutes ├── 📖 Core Concepts │ ├── How LinkMesh Works (Static Freeze Model) │ ├── Simulation vs. Freeze │ └── Link Safety (Layout Protection, HTML Parser) ├── ⚙️ Module Guides │ ├── Dashboard & PageRank │ ├── Bulk Settings & Category Rules │ ├── Orphan Rescue │ ├── Keyword Intelligence │ ├── 404 Scout │ ├── Click Stats │ ├── Review Queue & AI Generator │ └── Gutenberg Sidebar ├── 🔧 Advanced │ ├── Custom Post Types Support │ ├── Elementor Compatibility │ ├── CSV Import/Export │ ├── WP-Cron & Background Processing │ └── Performance Best Practices ├── 🔌 API Reference (future) ├── 🐛 Troubleshooting │ ├── Links Not Appearing │ ├── Simulation vs. Reality Discrepancy │ ├── Token Balance Issues │ └── Common Error Messages └── 📝 Changelog ``` --- ## 4. Website FAQ (faq.html) — Keep Mostly As-Is The current [`faq.html`](../../Downloads/project-bolt-sb1-zq57uuag/project/faq.html) works well as a presales FAQ. Structure: ``` faq.html ├── About LinkMesh (What is it, platforms, large sites) ├── Getting Started (Free trial, existing links, uninstall) ├── Billing & Plans (Annual vs LTD, refund, expiration, upgrade, transfer) ├── Product & Features (Editors supported, content types, manual override, performance) ├── Security & Privacy (Data handling, TLS, data deletion) └── Support (Response time, contact) ``` ### Minor improvements: 1. Add cross-link: "📖 For detailed how-to guides, visit our [Documentation](documentation.html)." 2. Add 1-2 questions about the new Semantic Engine / AI features. 3. Ensure FAQPage schema markup stays up-to-date. --- ## 5. Action Plan | # | Task | Where | Priority | |---|------|------|:---:| | 1 | Replace `class-ailm-faq-tab.php` with a lightweight hub page linking to the website | Plugin | 🔴 HIGH | | 2 | Add "?" help icons to module page headers in the plugin | Plugin | 🔴 HIGH | | 3 | Write full documentation on the website | `documentation.html` | 🟡 MEDIUM | | 4 | Minor updates to presales FAQ | `faq.html` | 🟢 LOW | --- ## 6. New Plugin FAQ Hub Page (Visual Concept) Instead of 6 tabs of tutorials — one clean page: ``` ┌─────────────────────────────────────────────────────────┐ │ LinkMesh: Semantic AI Internal Linking — Help │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ 📖 Full Documentation │ │ │ │ Complete guides for every module: Dashboard, │ │ │ │ Bulk Settings, Orphan Rescue, Keyword │ │ │ │ Intelligence, 404 Scout, Click Stats, │ │ │ │ Review Queue, Gutenberg Sidebar, and more. │ │ │ │ [Open Documentation →] linkmesh.co/docs │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ ❓ Frequently Asked Questions │ │ │ │ Pricing, billing, security, compatibility, │ │ │ │ and more. │ │ │ │ [Open FAQ →] linkmesh.co/faq │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ 📧 Need Help? │ │ │ │ Contact support@linkmesh.co │ │ │ │ We respond within 24 hours, 6 days a week. │ │ │ └─────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` Plus "?" help icons in each module page header: ``` Dashboard → linkmesh.co/documentation.html#dashboard Bulk Settings → linkmesh.co/documentation.html#bulk-settings Orphan Rescue → linkmesh.co/documentation.html#orphan-rescue ...etc. ```