pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-07-26 09:52:11 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
1c18be4f8f0e1dd458444f93ad79fe600af2b841
OmniRoute/docs/DOCUMENTATION_OVERHAUL_PLAN.md
Diego Rodrigues de Sa e Souza dd5a3db55e fix(docs): move DOCUMENTATION_OVERHAUL_PLAN out of the fumadocs guides collection (#4123) 
A cycle-internal docs housekeeping commit (635350ebb) relocated this internal
planning doc from docs/ root into docs/guides/, which `source.config.ts` globs
into the published fumadocs `docs` collection. The file has no frontmatter, so
`next build` (build:cli / Docker / Electron) failed to compile it:
`[MDX] invalid frontmatter … title: expected string, received undefined`,
breaking ALL three release-build fragments (npm/Docker/Electron) at release time.

Moving it back to docs/ root (which is NOT globbed by the collection) restores
the pre-cycle state and matches the documented intent — DOCUMENTATION_AUDIT_REPORT
lists it among docs/-root files that should never be published to the site.
Verified locally: `npm run build:cli` now completes green. No inbound links.
2026-06-17 19:58:28 -03:00

9.4 KiB
Raw Blame History

OmniRoute Documentation Overhaul Plan

Goal: Make all docs accessible to non-tech users while preserving technical depth for developers. Strategy: Two-tier docs (User Guide + Technical Reference) with cross-links.

Design Principles

  1. User Guide (new files in docs/guides/)

    • Plain language, no jargon
    • "Why → What → How" structure
    • Tables for comparisons
    • Copy-paste examples
    • "What's next?" at the end

  2. Technical Reference (existing files)

    • Keep as-is (already well-written)
    • Add "For Users" callout at top linking to user guide
    • Add "Prerequisites" section
    • Ensure consistent formatting

  3. Cross-Links

    • User guides link to technical docs for "learn more"
    • Technical docs link to user guides for "quick start"

Phase 1: User-Facing Quick Start Docs (Highest Impact)

1.1 docs/guides/QUICK-START.md — NEW

Replaces: Condensed version of README.md Content:

  • Install (npm, Docker, source)
  • Connect a free provider (3 steps)
  • Point your IDE to OmniRoute
  • Verify it works
  • "What's next?" → link to other guides

1.2 docs/guides/AUTO-COMBO-GUIDE.md — NEW

Complements: docs/routing/AUTO-COMBO.md Content:

  • What auto-combo does (30-second version)
  • Which auto should I use? (table)
  • How it picks providers (simple version)
  • Common questions (FAQ)
  • "Learn more" → link to technical reference

1.3 docs/guides/PROVIDERS-GUIDE.md — NEW

Complements: docs/reference/PROVIDER_REFERENCE.md Content:

  • What is a provider? (analogy)
  • How to connect a provider (step-by-step)
  • Free vs paid providers (table)
  • OAuth vs API key (which do I need?)
  • Troubleshooting connection issues
  • "Learn more" → link to provider reference

1.4 docs/guides/FREE-TIERS-GUIDE.md — NEW

Complements: docs/reference/FREE_TIERS.md Content:

  • What are free tiers? (analogy)
  • Best free providers (table with quotas)
  • How to stack free tiers for unlimited usage
  • Common questions (FAQ)
  • "Learn more" → link to free tiers reference

1.5 docs/guides/TROUBLESHOOTING.md — REWRITE

Current: Technical, code-heavy New: "I see X → Do Y" format Content:

  • Problem → Solution table
  • Common error messages (with screenshots)
  • "Still stuck?" → link to community

Phase 2: Refine Existing User Docs

2.1 docs/guides/USER_GUIDE.md — UPDATE

Changes:

  • Add "What you'll learn" section at top
  • Remove jargon, explain terms
  • Add step-by-step screenshots
  • Add "Common mistakes" section

2.2 docs/guides/SETUP_GUIDE.md — UPDATE

Changes:

  • Add "Prerequisites" section
  • Simplify commands (one-liners)
  • Add "Verify it works" step
  • Add "Troubleshooting" section

2.3 docs/guides/FEATURES.md — UPDATE

Changes:

  • Add "Why this matters" for each feature
  • Add use-case examples
  • Add "How to enable" for each feature
  • Add screenshots

2.4 docs/guides/DOCKER_GUIDE.md — UPDATE

Changes:

  • Add "Docker for beginners" section
  • Simplify commands
  • Add "Common Docker issues" section
  • Add "What's next?" section

2.5 docs/guides/ELECTRON_GUIDE.md — UPDATE

Changes:

  • Add "What is Electron?" explanation
  • Add screenshots
  • Add "Common issues" section

2.6 docs/guides/TERMUX_GUIDE.md — UPDATE

Changes:

  • Add "What is Termux?" explanation
  • Add step-by-step with screenshots
  • Add "Common issues" section

2.7 docs/guides/PWA_GUIDE.md — UPDATE

Changes:

  • Add "What is a PWA?" explanation
  • Add step-by-step with screenshots
  • Add "Common issues" section

2.8 docs/guides/I18N.md — UPDATE

Changes:

  • Add "How to change language" (user perspective)
  • Add "How to contribute translations" (contributor perspective)

2.9 docs/guides/KIRO_SETUP.md — UPDATE

Changes:

  • Add "What is Kiro?" explanation
  • Add step-by-step with screenshots
  • Add "Common issues" section

2.10 docs/guides/UNINSTALL.md — UPDATE

Changes:

  • Add "Why uninstall?" section (common reasons)
  • Add "Before you uninstall" checklist
  • Simplify commands

Phase 3: Technical Docs (Add Cross-Links, Keep As-Is)

3.1 docs/architecture/ (6 files)

Changes: Add "For Users" callout at top → link to user guide

  • ARCHITECTURE.md
  • AUTHZ_GUIDE.md
  • CODEBASE_DOCUMENTATION.md
  • MONITORING_SECTIONS.md
  • REPOSITORY_MAP.md
  • RESILIENCE_GUIDE.md

3.2 docs/frameworks/ (16 files)

Changes: Add "For Users" callout at top → link to user guide

  • A2A-SERVER.md
  • AGENT-SKILLS.md
  • AGENTBRIDGE.md
  • AGENT_PROTOCOLS_GUIDE.md
  • CLOUD_AGENT.md
  • EMBEDDED-SERVICES.md
  • EVALS.md
  • GAMIFICATION.md
  • MCP-SERVER.md
  • MEMORY.md
  • OPENCODE.md
  • PLAYGROUND_STUDIO.md
  • SEARCH_TOOLS_STUDIO.md
  • SKILLS.md
  • TRAFFIC_INSPECTOR.md
  • WEBHOOKS.md

3.3 docs/security/ (9 files)

Changes: Add "For Users" callout at top → link to user guide

  • CLI_TOKEN.md
  • CLI_TOKEN_AUTH.md
  • COMPLIANCE.md
  • ERROR_SANITIZATION.md
  • GUARDRAILS.md
  • PUBLIC_CREDS.md
  • ROUTE_GUARD_TIERS.md
  • SOCKET_DEV_FINDINGS.md
  • STEALTH_GUIDE.md

3.4 docs/ops/ (8 files)

Changes: Add "For Users" callout at top → link to user guide

  • COVERAGE_PLAN.md
  • E2E_DASHBOARD_SHAKEDOWN_v3.8.0.md
  • FLY_IO_DEPLOYMENT_GUIDE.md
  • PROXY_GUIDE.md
  • RELEASE_CHECKLIST.md
  • SQLITE_RUNTIME.md
  • TUNNELS_GUIDE.md
  • VM_DEPLOYMENT_GUIDE.md

3.5 docs/compression/ (5 files)

Changes: Add "For Users" callout at top → link to user guide

  • COMPRESSION_ENGINES.md
  • COMPRESSION_GUIDE.md
  • COMPRESSION_LANGUAGE_PACKS.md
  • COMPRESSION_RULES_FORMAT.md
  • RTK_COMPRESSION.md

3.6 docs/routing/ (3 files)

Changes: Add "For Users" callout at top → link to user guide

  • AUTO-COMBO.md (→ link to AUTO-COMBO-GUIDE.md)
  • QUOTA_SHARE.md
  • REASONING_REPLAY.md

3.7 docs/reference/ (5 files)

Changes: Add "For Users" callout at top → link to user guide

  • API_REFERENCE.md
  • CLI-TOOLS.md
  • ENVIRONMENT.md
  • FREE_TIERS.md (→ link to FREE-TIERS-GUIDE.md)
  • PROVIDER_REFERENCE.md (→ link to PROVIDERS-GUIDE.md)

3.8 Other Docs (keep as-is)

  • docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md — Already user-friendly
  • docs/marketing/TIERS.md — Already user-friendly
  • docs/diagrams/README.md — Keep as-is
  • docs/dev/plugins.md — Developer-only
  • docs/plugins/PLUGIN_SDK.md — Developer-only
  • docs/providers/ZED-DOCKER.md — Provider-specific
  • docs/AGENTROUTER.md — Provider-specific
  • docs/PROVIDERS.md — Provider-specific
  • docs/README.md — Keep as-is
  • docs/SUBMIT_PR.md — Contributor-only
  • docs/releases/v3.8.0.md — Release notes
  • docs/research/ — Internal research
  • docs/specs/ — Internal specs
  • docs/openspec/ — Internal specs
  • docs/superpowers/ — Internal plans

Phase 4: Update Main README.md

Changes:

  • Add "Quick Start" section (3 steps)
  • Add "Which auto should I use?" table
  • Add "Free providers" table
  • Add "Common questions" section
  • Link to user guides

Execution Order

Week 1: Phase 1 (User-Facing Quick Start Docs)

  1. docs/guides/QUICK-START.md — NEW
  2. docs/guides/AUTO-COMBO-GUIDE.md — NEW
  3. docs/guides/PROVIDERS-GUIDE.md — NEW
  4. docs/guides/FREE-TIERS-GUIDE.md — NEW
  5. docs/guides/TROUBLESHOOTING.md — REWRITE

Week 2: Phase 2 (Refine Existing User Docs)

  1. docs/guides/USER_GUIDE.md — UPDATE
  2. docs/guides/SETUP_GUIDE.md — UPDATE
  3. docs/guides/FEATURES.md — UPDATE
  4. docs/guides/DOCKER_GUIDE.md — UPDATE
  5. docs/guides/ELECTRON_GUIDE.md — UPDATE
  6. docs/guides/TERMUX_GUIDE.md — UPDATE
  7. docs/guides/PWA_GUIDE.md — UPDATE
  8. docs/guides/I18N.md — UPDATE
  9. docs/guides/KIRO_SETUP.md — UPDATE
  10. docs/guides/UNINSTALL.md — UPDATE

Week 3: Phase 3 (Technical Docs Cross-Links)

  1. docs/architecture/ — Add cross-links
  2. docs/frameworks/ — Add cross-links
  3. docs/security/ — Add cross-links
  4. docs/ops/ — Add cross-links
  5. docs/compression/ — Add cross-links
  6. docs/routing/ — Add cross-links
  7. docs/reference/ — Add cross-links

Week 4: Phase 4 (Update Main README.md)

  1. Update README.md with user-friendly sections

Success Metrics

  • User can install OmniRoute in < 5 minutes (QUICK-START.md)
  • User can connect a provider in < 3 minutes (PROVIDERS-GUIDE.md)
  • User can use auto-combo in < 1 minute (AUTO-COMBO-GUIDE.md)
  • User can find free providers in < 2 minutes (FREE-TIERS-GUIDE.md)
  • User can troubleshoot common issues in < 5 minutes (TROUBLESHOOTING.md)
  • All technical docs link to user guides
  • All user guides link to technical docs

File Naming Convention

  • User guides: docs/guides/[FEATURE]-GUIDE.md (e.g., AUTO-COMBO-GUIDE.md)
  • Technical docs: Keep existing names (e.g., docs/routing/AUTO-COMBO.md)
  • Cross-links: "For Users" callout at top of technical docs

Template for User Guides

# [Feature Name]: [One-Line Description]

## What It Does

[2-3 sentences explaining what the feature does in plain language]

## Quick Start

[Step-by-step instructions to get started]

## [Main Section]

[Detailed explanation with tables, examples, screenshots]

## Common Questions

[FAQ section with common questions and answers]

## What's Next?

[Links to related guides and technical docs]

Template for Technical Doc Cross-Links

> **For Users**: Looking for a quick start? See the [User Guide](../guides/[FEATURE]-GUIDE.md).

> **Prerequisites**: [List prerequisites]
Reference in New Issue View Git Blame Copy Permalink