# Sparkth end-user documentation — proposed plan

Responds to [edly-io/sparkth#795](https://github.com/edly-io/sparkth/issues/795)
("There is no documentation for an end user").

## Audience split

Sparkth's existing docs serve **operators and plugin developers**. End users
are different people with different questions:

| Audience | Typical questions |
|---|---|
| **Educators / course authors** | How do I generate a course? How do I connect my AI assistant? What do the plugins (Canvas, Moodle, Open edX) do for me? |
| **Learners / chat users** | How do I sign up? How does chat use my uploaded documents? What happens to my files? |
| **Workspace admins** (non-developer) | How do I manage users, whitelist access, read the analytics pages? |

## Proposed structure (`docs/users/`)

1. **Getting started** — account, verification, first login, dashboard tour.
   *(Written in full in this sample: [`getting-started.md`](getting-started.md).)*
2. **Connecting an AI assistant** — what the MCP server is in plain words;
   connecting Claude/other MCP clients to `/ai/mcp`; which tools appear and
   what they do (per enabled plugin).
3. **Generating course content** — the course-generation prompt, building
   activities (PXC), reviewing and iterating on generated material.
4. **Chat with your documents** — attaching documents, when retrieval does
   and doesn't run (plain-language version of the existing
   `chat-retrieval.md`, which is written for developers), document statuses
   (ready / ingesting / failed), deleting documents.
5. **Resources** — uploading and organizing files; Google Drive connection.
6. **LMS integrations for course authors** — what connecting Canvas, Moodle,
   or Open edX gives you; pushing generated content to your LMS.
7. **Settings & AI keys** — bringing your own model key, choosing a model,
   what each setting changes.
8. **For workspace admins** — user management, the whitelist page, the
   analytics pages (logins), auditability in plain words.
9. **FAQ & troubleshooting** — login/verification problems, "why didn't chat
   read my document", "my AI assistant can't see Sparkth tools".

## Conventions

- Every page answers "what can I do here" in the first two sentences.
- Screenshots on every page with a UI surface; captured at a fixed window
  size for consistent rendering.
- No internal class/function names on user pages — those stay in the
  developer docs; cross-link instead.
- Published in the existing mkdocs site under a separate "Using Sparkth"
  nav section, so one `make docs` builds both.

## Delivery estimate (paid engagement)

All nine sections, screenshots from a live instance, mkdocs nav integration,
one revision round included: **72 hours** from access to a staging instance.