Plan: User Testing Guide for Non-Technical Users

On this page

Status

COMPLETE

Context

CRAIG’s documentation is excellent for developers but assumes familiarity with Docker, terminals, and microservice architecture. Non-technical child welfare workers (caseworkers, supervisors, eligibility workers, finance staff) need to be able to launch CRAIG locally to evaluate and test it. The existing DevStack Guide (592 lines) is a comprehensive technical reference — it should NOT be modified. Instead, we create a separate "User Testing Guide" that provides a step-by-step walkthrough from zero to a running CRAIG instance, written in plain English with no assumed technical knowledge.

Files to Create/Modify

File Action

docs/modules/ROOT/pages/user-testing-guide.adoc

New — the guide itself (~450 lines)

docs/modules/ROOT/nav.adoc

Add guide entry after "Why CRAIG?" and plan entry under Plans section

MEMORY.md

Note the new page

Style Rules

  • Never use "devstack" — call it "CRAIG" or "the CRAIG test environment"

  • Never mention Rust, RabbitMQ, PostgreSQL, Keycloak, Garage, Axum, or SQLx by name. Use plain equivalents: "the login server," "the database," etc.

  • Always show both PowerShell (Windows) and bash (macOS/Linux) commands

  • Describe expected output after every command

  • Define terms on first use: terminal, Docker, etc.

  • Keep paragraphs to 2-3 sentences max

  • Use :toc: left, [TIP], [NOTE], [IMPORTANT], [WARNING] admonitions matching existing docs

  • Link to devstack.adoc once at the end for advanced topics; don’t duplicate it

Document Structure

1. What Is This Guide?

CRAIG is a child welfare information system. This section explains that the guide walks users through running a complete copy on their own computer to explore, test workflows, and provide feedback. Define Docker in one parenthetical. No data leaves the computer; test data is fictional. Time estimate: 20-30 minutes first time, 1-2 minutes after.

2. What You Will Need

Checklist: Windows/macOS/Linux computer, 16 GB RAM, 10 GB disk, internet connection, administrator access. Note: if agency laptop restricts installation, ask IT to install Docker Desktop.

3. Step 1: Install Docker

Per-OS sub-sections (Windows, macOS, Linux Ubuntu/Debian):

  • Windows: Download Docker Desktop, choose WSL 2 backend, restart, allocate 8 GB RAM in Settings > Resources, verify with docker --version in PowerShell.

  • macOS: Download Docker Desktop (Apple Silicon or Intel), drag to Applications, allocate 8 GB RAM, verify in Terminal.

  • Linux: apt-get install docker.io docker-compose-v2, add user to docker group, log out/back in, verify.

4. Step 2: Get the CRAIG Source Code

Two options: download ZIP from GitLab (easier) or git clone. Per-OS instructions for opening a terminal in the CRAIG folder. Verification: run cargo xtask dev status to confirm correct directory and environment.

5. Step 3: Start CRAIG

Commands (PowerShell and bash). "What to Expect During Startup" sub-section with plain-language explanation and expected terminal output showing all 8 services reporting healthy. Timing tips: 5-10 minutes first time, 1-2 minutes cached.

6. Step 4: Log In

Open browser to http://localhost:8080, click "Sign In," enter credentials. Inline test user table:

Username Password Roles What You Can Access

admin

password

Administrator

Everything including Rules and Security

jane.doe

password

Caseworker + Supervisor

Dashboard, Intake, Cases, Placement, Exchange, Financial

bob.smith

password

Caseworker + Eligibility Worker

Dashboard, Intake, Cases, Placement, Financial

Derived from actual base.html role checks: is_caseworker_or_above() gates Intake/Cases/Placement; is_admin() gates Rules/Security; has_any_role(["supervisor","admin","icpc_coordinator"]) gates Exchange; has_any_role(["eligibility_worker","supervisor","admin"]) gates Financial.

7. Step 5: Explore CRAIG

Guided tour: Dashboard, Intake, Cases, Placement, Financial, Exchange, Rules (admin), Security (admin). Each module gets 2-3 sentences explaining what it shows and what to try.

8. Stopping CRAIG

stop command preserves data; next start resumes.

9. Starting with Fresh Data

restart command wipes everything and reloads test data.

10. Checking Status

status command with example output.

11. Troubleshooting

Common problems: Docker not running, startup >15 minutes (RAM), port conflicts, localhost:8080 not loading, login failures, session expiry.

12. For More Information

Links to DevStack Guide, Architecture, Why CRAIG?, and GitLab repository.

Verification

  1. antora antora-playbook.yml builds without errors

  2. New page appears in the Antora site navigation after "Why CRAIG?"

  3. All cross-references resolve

  4. Read-through by someone unfamiliar with Docker confirms instructions are followable

  5. Devstack commands shown in the guide match actual script output

Edit this page · latest