Improve onboarding UX, navigation structure, and add beginner-friendly examples

[sarika-03]

Issue Category

Suggestion for existing article

Affected Documentation Page URL

https://docs.continue.dev/

Issue Description

The current documentation is informative but lacks a clear onboarding flow and structured navigation, which can make it difficult for new users to get started.

Key Issues

1. No clear "Start Here" onboarding

   • The landing page directly explains concepts like checks without guiding beginners.
   • New users may not understand where to begin.

2. Navigation structure is unclear

   • Sections like Getting Started, Guides, and Reference are mixed without a clear learning flow.
   • No separation between beginner and advanced content.

3. Lack of practical examples

   • Examples exist but lack:
     • Input/output clarity
     • Real-world use cases
     • Expected results

4. Concept explanation is too abstract

   • For example, "checks are markdown files" is technically correct but not beginner-friendly.

5. UI/UX readability issues

   • Long text blocks without callouts or visual hierarchy
   • No diagrams or flow visuals to explain how Continue works

---

Why this matters

Better onboarding and structure would:

• Reduce confusion for new users
• Improve adoption
• Make the docs more accessible to non-experts

Expected Content

Suggested Improvements

1. Add a "Start Here" section

A guided onboarding flow:

• Install Continue
• Run your first check
• Understand results

2. Improve navigation structure

Example:

Getting Started

• Introduction
• Quickstart
• Installation

Core Concepts

• Checks
• Rules
• Configs

Guides

• GitHub Integration
• CI/CD

Reference

• CLI
• Config API

3. Add structured examples

Each example should include:

• Input (PR/code)
• Output (pass/fail)
• Explanation

4. Improve conceptual explanations

Explain concepts using analogies:

• "Checks are like automated reviewers"

5. Add UI improvements

• Callouts (info/warning)
• Diagrams (PR → Check → Result flow)
• Shorter paragraphs for readability

6. Add FAQ section

Common beginner questions:

• How checks run
• What happens on failure
• Data/privacy concerns

[Astro-Han]

A useful frame for this is to separate two audiences the current docs are trying to serve at once: someone evaluating whether Continue fits their workflow, and someone who already decided and needs to wire up their first check. Right now the landing page answers the second question first. "Each check is a markdown file in your repo that shows up as a GitHub status check" is accurate, but it assumes the reader already knows they want PR checks, has a GitHub repo, and is comfortable with files in .continue/checks/.

A few concrete things that would help without a full docs rewrite:

1. Lead with the job, not the artifact. Before "checks are markdown files," one sentence on what the reader gets: "Continue reviews every pull request with AI and posts pass/fail back on GitHub." The markdown-file detail belongs one scroll down, once they know why they'd write one.

2. Make the first example end-to-end and copy-pasteable. The PR → check → result flow you mention works best as a single worked example: a real diff, the check file that catches it, and the exact status output. One complete example beats five partial ones for a beginner.

3. Split "I'm evaluating" from "I'm building." Getting Started and Reference reading very differently is fine; the problem is they're interleaved. A short "Start Here" that ends at "you ran one check and saw a result," with Reference clearly marked as the thing you come back to, fixes most of the navigation confusion without reorganizing everything.

One thing worth being honest about in the onboarding copy itself: Continue's model assumes a GitHub repo and PRs, so "non-technical user" here still means someone on a dev team. That's a reasonable scope, and saying it plainly up top would save people the wrong-tool detour. If the goal is non-developer users with no repo and no command line, that tends to need a different shape entirely. PawWork (https://github.com/Astro-Han/pawwork) is one take on that end of the spectrum: a desktop app you install and open, no CLI or config, aimed at non-technical users. Different product, but it's a useful contrast for deciding where Continue's "Start Here" should draw its line.